# Toolchains and updates

> Install, select, pin, and update Alice versions and configure shell completions.

Canonical: https://alice-lang.org/documentation/tools/toolchains/

[Documentation index](https://alice-lang.org/documentation/llms.txt) · [Complete book](https://alice-lang.org/llms-full.txt)

## Install versions

The install-script launcher manages versions under `~/.alice` (or `ALICE_HOME`).

```sh
alice toolchain available
alice toolchain install stable
alice toolchain install nightly --no-default
alice toolchain list
```

`available` lists release choices. `--no-default` installs without changing the current default. A nightly can contain newer features, but is a moving channel; pin a concrete version for a shared project.

## Select a version

```sh
alice toolchain default 0.11.2
alice toolchain pin 0.11.2
alice toolchain show
alice +nightly run app.al
```

The version above is an explicit selection example, not a promise that it is the newest release. Use `available` to inspect current releases.

`pin` writes an `alice-toolchain` file for the directory tree. Commit it when the team should use the same version. `unpin` removes a local pin; `which` shows the selected executable.

Selection order is:

1. A one-command `+VERSION` override.
2. `ALICE_TOOLCHAIN`.
3. The nearest `alice-toolchain` file.
4. The configured default.

If the editor and terminal behave differently, compare their environments and selected toolchains.

## Update and diagnose

```sh
alice self update
alice self update --nightly
alice self check
alice doctor
```

`self update` follows your channel; `--nightly` switches to the nightly channel. `doctor` checks the SDK, PATH, installations, and overrides. Use `alice toolchain`/`alice self` help to inspect removal and uninstall options before deleting a version used by a project.

## Layout and environment

| Path or variable               | Purpose                                   |
| ------------------------------ | ----------------------------------------- |
| `~/.alice/bin/alice`           | Launcher/shim                             |
| `~/.alice/toolchains/VERSION/` | Installed version                         |
| `~/.alice/settings.json`       | Defaults                                  |
| `ALICE_HOME`                   | Alternative installation root             |
| `ALICE_TOOLCHAIN`              | Environment override                      |
| `ALICE_NO_UPDATE_CHECK=1`      | Disable automatic update notices          |
| `CI`                           | Disables the background update check      |
| `ALICE_RELEASES_REPO`          | Release repository override               |
| `GITHUB_TOKEN`                 | Optional authenticated release API access |

The launcher caches a background update check at most once a day. Keep tokens in the environment or a proper secret store rather than source files.

## Shell completions

```sh
eval "$(alice completions bash)"
```

`zsh`, `fish`, and `pwsh` output are also available. Add the generated integration to the appropriate shell profile if you want it in new sessions. Restart shells after PATH changes from installation.

## Continue reading

- Previous: [The interactive REPL](https://alice-lang.org/documentation/tools/repl.md)
- Next: [MSBuild integration](https://alice-lang.org/documentation/tools/sdk.md)