aftman 0.2.6

Aftman is a command line toolchain manager
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175

# Aftman
Aftman is a toolchain manager. It enables installing project-specific command line tools and switching between them seamlessly.

```bash
$ rojo --version
Rojo 6.2.0

$ cat ~/.aftman/aftman.toml
[tools]
rojo = "rojo-rbx/rojo@6.2.0"

$ cd uses-rojo-7
$ rojo --version
Rojo 7.1.0

$ cat aftman.toml
[tools]
rojo = "rojo-rbx/rojo@7.1.0" 
```

## Supported Platforms
Aftman supports:

- Windows (x86, x86-64)
- macOS (x86-64, AArch64)
- Linux (x86, x86-64)

## Installation
You can install Aftman by downloading a pre-built binary for your platform from Aftman's [GitHub Releases Page](https://github.com/LPGhatguy/aftman/releases).

Once you have the release unzipped, run:

```bash
./aftman self-install
```

This will install Aftman to its own bin directory and update your system's `PATH` environment variable for you.

## Getting Started
To create a new `aftman.toml` file in your current directory, run

```bash
aftman init
```

To add a new tool, you can follow the instructions in the file, or run

```bash
aftman add rojo-rbx/rojo

# install a specific version
aftman add rojo-rbx/rojo@6.2.0

# install with a different binary name
aftman add BurntSushi/ripgrep rg
```

If your PATH is configured correctly (see [Installation](#installation)), you will now be able to run that tool from your project.

To install a tool system-wide so that it can be used anywhere, edit `~/.aftman/aftman.toml` or run

```bash
aftman add --global rojo-rbx/rojo
```

To install all tools listed by your `aftman.toml` files, run

```bash
aftman install
```

## Subcommands
For detailed help information, run `aftman --help`.

### `aftman init`
Usage:

```bash
aftman init [path]
```

Creates a new `aftman.toml` file in the given directory. Defaults to the current directory.

### `aftman add`
Usage:

```bash
aftman add [--global] <tool-spec> [tool-alias]
```

Installs a new tool with the given tool spec and optional alias to use for installing the tool.

Examples:

```bash
# Install the latest version of Rojo in the nearest aftman.toml file
aftman add rojo-rbx/rojo

# Install the latest version of Rojo globally
aftman add --global rojo-rbx/rojo

# Install a specific version of Rojo locally
aftman add rojo-rbx/rojo@6.2.0

# Install Rojo with a different binary name
aftman add rojo-rbx/rojo@6.2.0 rojo6
```

### `aftman install`
Usage:

```bash
aftman install [--no-trust-check]
```

Install all tools listed in `aftman.toml` files based on your current directory.

If `--no-trust-check` is given, all tools will be installed, regardless of whether they are known. This should generally only be used in CI environments. To trust a specific tool before running `aftman install`, use `aftman trust <tool>` instead.

### `aftman self-install`
Usage:

```bash
aftman self-install
```

Installs Aftman, upgrades any references to Aftman, and adds `aftman` to your system `PATH` if supported.

Whenever you upgrade Aftman, run this command. Aftman makes copies of itself to mimic the tools it installs, and this command will ensure those copies get updated as well.

### `aftman trust`
Usage:

```bash
aftman trust <tool-name>
```

Adds a tool to the list of trusted tools.

Aftman prompts the user before installing new tools. Running `aftman trust` beforehand skips this prompt. This is useful when running automation that depends on a tool from a known location.

### `aftman list`
*Added in Aftman 0.2.6.*

Usage:

```bash
aftman list
```

Lists all tools currently managed by Aftman.

### `aftman update`
**This subcommand is not yet implemented.**

## Differences from Foreman
Aftman is spiritually very similar to [Foreman], a project I created at Roblox.

I'm hoping to fix some of the core design mistakes I made in Foreman and also take a little more care with the codebase. Roughly:

* **Exact version dependencies.** Using a range here has tripped up lots of users, so Aftman uses exact versions in all configuration files.
* **Commands to install, uninstall, and upgrade tools.** Editing a global, tucked-away toml file by hand is rough.
* **Change model to no longer trust-by-default.** Aftman prompts before downloading new tools. ([Roblox/foreman#16]).
* **Better strategy for storing executables.** ([Roblox/foreman#11])
* **Better heuristics for picking the right artifacts for your platform.** Aftman uses your Compiler, OS, architecture, and will eventually support custom patterns. ([Roblox/foreman#18])
* **Proper error handling.** Unlike Foreman, which uses `Result::unwrap` liberally, Aftman has good error hygiene with helpful context attached.
* **Less Roblox-angled.** Aftman does not market itself as being for Roblox development. It is a generally useful tool that can install all sorts of CLI tools.

[Foreman]: https://github.com/Roblox/foreman
[Roblox/foreman#11]: https://github.com/Roblox/foreman/issues/11
[Roblox/foreman#16]: https://github.com/Roblox/foreman/issues/16
[Roblox/foreman#18]: https://github.com/Roblox/foreman/issues/18

## License
Aftman is available under the terms of the MIT license. See <https://opensource.org/licenses/MIT> or [LICENSE](LICENSE) for details.