# Installation

Install `cademi` with a one-line script on macOS, Linux, or Windows. The CLI then keeps itself up to date and verifies the signature of every release before installing it.

## macOS and Linux

```sh
curl -fsSL https://cli.cademi.dev/install.sh | bash
```

The script:

1. Detects the system (`darwin` or `linux`) and the architecture (`amd64` or `arm64`). On an Apple silicon Mac, it installs the `arm64` build even when the shell runs under Rosetta.
2. Downloads the latest stable release and checks the package against the release's SHA-256 checksums.
3. Installs the binary at `~/.cademi/bin/cademi`, without `sudo`.
4. Adds `~/.cademi/bin` to your `PATH`, once, in the startup file of your shell:

| Shell | File |
|---|---|
| zsh | `~/.zshrc` (or `$ZDOTDIR/.zshrc`) |
| bash | `~/.bash_profile` on macOS, `~/.bashrc` on Linux |
| fish | `~/.config/fish/conf.d/cademi.fish` |
| Other | `~/.profile` |

5. Prints the installed version.

Open a new terminal to use `cademi`, or add the directory to the current session:

```sh
export PATH="$HOME/.cademi/bin:$PATH"
```

The script requires `curl`.

## Windows

In PowerShell:

```powershell
irm https://cli.cademi.dev/install.ps1 | iex
```

The script downloads the `amd64` or `arm64` build, checks its SHA-256 checksum, installs `cademi.exe` in `%USERPROFILE%\.cademi\bin`, and adds that directory to your user `PATH`. Open a new terminal to use `cademi`.

## Installer options

Both scripts read these environment variables:

| Variable | Effect |
|---|---|
| `CADEMI_VERSION` | Version to install, for example `0.1.1`. Defaults to the latest version of the channel. |
| `CADEMI_CHANNEL` | `stable` (default) or `beta`. |
| `CADEMI_INSTALL_DIR` | Directory for the binary. Defaults to `~/.cademi/bin` (`%USERPROFILE%\.cademi\bin` on Windows). |
| `CADEMI_NO_MODIFY_PATH` | Set to `1` to leave your shell startup files unchanged. macOS and Linux only. |
| `CADEMI_DOWNLOAD_URL` | Base URL of a mirror that serves the same release files. Defaults to `https://cli.cademi.dev`. |

The variable must reach the shell that runs the script, not `curl`:

```sh
curl -fsSL https://cli.cademi.dev/install.sh | CADEMI_VERSION=0.1.1 bash
```

```powershell
$env:CADEMI_VERSION = '0.1.1'; irm https://cli.cademi.dev/install.ps1 | iex
```

Install the CLI where you can write to the directory. Updates replace the binary in place, so `cademi update` fails in a directory that needs `sudo` or administrator rights.

## Checking the installation

```sh
cademi version
```

```text
cademi 0.1.4 (api 3.4.5, commit f4cdf2e)
```

The output shows the CLI version, the API release the CLI was built for, and the build commit. Run `cademi env` to see the path of the executable and the rest of the effective configuration ([Environment and diagnostics](https://cademi.dev/cli/environment.md)).

## Shell completion

`cademi completion <shell>` prints a completion script for `bash`, `zsh`, `fish`, or `powershell`. Completion covers commands, flags, and the allowed values of enum flags.

```sh
# zsh, current session
source <(cademi completion zsh)

# fish, every new session
cademi completion fish > ~/.config/fish/completions/cademi.fish
```

```powershell
cademi completion powershell | Out-String | Invoke-Expression
```

`cademi completion <shell> --help` explains how to load the script in every new session for each shell. The bash script requires the `bash-completion` package.

## Updating

```sh
cademi update             # install the latest version of your channel
cademi update --check     # only report whether a newer version exists
cademi update --version 0.1.1   # install a specific version, also to roll back
```

`cademi update --check` prints either `cademi 0.1.4 is the latest stable version` or the newer version that is available.

`--force` installs the latest version even when you already have it.

### Automatic updates

At most once every 24 hours, when you run a command in a terminal, `cademi` checks for a newer release of your channel in the background, without delaying the command. When it finds one, it downloads, verifies, and installs it, and the next command tells you which version it updated from and to. If the update cannot be installed, the next command tells you that a newer version is available and suggests `cademi update`.

Automatic updates are off when any of these applies:

| Condition | How to set it |
|---|---|
| Turned off in the configuration | `cademi update --auto off` (turn back on with `cademi update --auto on`) |
| `CADEMI_DISABLE_AUTOUPDATE` has any value | `export CADEMI_DISABLE_AUTOUPDATE=1` |
| `CI` has any value | Set by most CI services |

`cademi env auto_update` shows whether automatic updates are on and why.

To stay on a specific version, install it with `cademi update --version <version>` and turn off automatic updates. Otherwise, the next automatic check moves you to the latest version again.

### Channels

`stable` is the default channel. `beta` also receives pre-release versions.

```sh
cademi update --channel beta
```

`--channel` saves the channel and installs its latest version. Switching back to `stable` does not downgrade a newer beta version: install a stable version with `--version`.

## Release verification

Every release publishes, for each platform, a package named `cademi_<version>_<os>_<arch>.tar.gz` (`.zip` on Windows), a `checksums.txt` file with the SHA-256 of every package, and `checksums.txt.sig`, an ed25519 signature of `checksums.txt`.

- The install scripts check the package against `checksums.txt` and stop on a mismatch.
- `cademi update` and automatic updates also verify `checksums.txt.sig` with the Cademí release key built into the binary before checking the package. If the signature or the checksum does not match, nothing is installed.

To verify a package yourself, download it together with `checksums.txt` from `https://cli.cademi.dev/download/v<version>/`:

```sh
curl -fsSLO https://cli.cademi.dev/download/v0.1.1/cademi_0.1.1_linux_amd64.tar.gz
curl -fsSLO https://cli.cademi.dev/download/v0.1.1/checksums.txt
sha256sum --ignore-missing -c checksums.txt   # on macOS: shasum -a 256 --ignore-missing -c checksums.txt
```

`checksums.txt.sig` contains the base64-encoded ed25519 signature of the exact bytes of `checksums.txt`. The release public key, base64-encoded, is `4olluf48ZsVOQPpH0+EXhZwkLP5Mn3XOynPuPiKkhCI=`.

## Uninstalling

1. Sign out of every profile. `cademi auth logout` revokes the OAuth session of a human-mode profile, removes the profile's secrets from the keychain, and deletes the profile:

```sh
cademi profiles list
cademi auth logout --profile <name>
```

2. Find the configuration directory with `cademi env config_dir` and delete it. It holds the profiles (without secrets) and the update state.
3. Delete the binary directory: `~/.cademi` on macOS and Linux, `%USERPROFILE%\.cademi` on Windows.
4. Remove the `PATH` entry. On macOS and Linux, delete the `# cademi` comment and the line after it from your shell startup file (listed in [macOS and Linux](https://cademi.dev/cli/installation.md#macos-and-linux)). On Windows, remove `%USERPROFILE%\.cademi\bin` from the `Path` user environment variable.

Signing out does not revoke the API credential itself. Revoke it in the Cademí dashboard or with `cademi credentials delete <credential_id>` if you no longer need it.