Install the CLI

When the installer finishes, open a new terminal and run:

alterac-ai --version

The output should match the version reported by the installer. Then initialize alterac.ai in a repository.

Pass a published stable version instead of installing the latest release. Replace 1.2.3 with the version you need.

curl -fsSL https://alterac.ai/install.sh | bash -s 1.2.3

Rerun the install command above to upgrade to the latest stable version. The CLI does not update itself. If an ordinary command reports a newer version, follow its link back here and rerun the installer.

A separate warning about outdated repository guidance means you should also run alterac-ai docs-update from your initialized repository. Installing the executable and refreshing repository guidance are separate steps.

The scripts download the selected release, verify its archive size and SHA-256 checksum, and install for your user account. No administrator access is needed. Run the Unix command as your normal user, without sudo.

• On macOS, Linux, and WSL, the binary goes in ~/.local/bin. If needed, the script appends one PATH line to ~/.zshrc for Zsh, ~/.bash_profile for Bash on macOS, or ~/.bashrc for Bash on Linux. For other shells it prints the line to add yourself.
• On Windows, the binary goes in %USERPROFILE%\.local\bin. The script updates only your user PATH. Already-open terminals need to restart.

The installer reports the folder and any PATH changes. On Unix, the piped installer cannot change PATH in your current terminal; open a new terminal after a shell-file update. On Windows, it also updates the PowerShell session running the script. Other already-open terminals need to restart, including the parent Command Prompt when it launches PowerShell.

Set these environment variables before running the script. Use a folder owned by your normal user account.

Set ALTERAC_AI_NO_MODIFY_PATH before running the installer.

• Default: Unset; automatic PATH setup is enabled.
• Value: Set exactly 1 to skip PATH changes. Other values leave automatic setup enabled.
• Effect: On macOS, Linux, and WSL, no shell file is changed. On Windows, neither user PATH nor the script's current-session PATH is changed. Add the installation directory to PATH manually as described below.

Set ALTERAC_AI_INSTALL_DIR before running the installer.

• Default: ~/.local/bin on macOS, Linux, and WSL; %USERPROFILE%\.local\bin on Windows.
• Value: An absolute user-owned directory. Unset or empty uses the default; Windows also treats whitespace-only values as unset.
• Effect: Installs in that directory instead. Automatic PATH setup uses the chosen directory unless disabled with ALTERAC_AI_NO_MODIFY_PATH=1.

These examples choose a custom folder and disable PATH modification. Omit either variable to keep its default.

Apply the variables to bash, which runs the script, rather than only to curl:

curl -fsSL https://alterac.ai/install.sh | ALTERAC_AI_NO_MODIFY_PATH=1 ALTERAC_AI_INSTALL_DIR="$HOME/tools/alterac-ai" bash

The variables apply only to this installer invocation.

$env:ALTERAC_AI_NO_MODIFY_PATH = '1'
$env:ALTERAC_AI_INSTALL_DIR = "$env:USERPROFILE\tools\alterac-ai"
irm https://alterac.ai/install.ps1 | iex

These settings remain in this PowerShell session until you remove them or close it. To restore installer defaults in the same session:

Remove-Item Env:ALTERAC_AI_NO_MODIFY_PATH, Env:ALTERAC_AI_INSTALL_DIR -ErrorAction SilentlyContinue

From Command Prompt, set variables with set "NAME=value" before running its install command; the child PowerShell process inherits them:

set "ALTERAC_AI_NO_MODIFY_PATH=1"
set "ALTERAC_AI_INSTALL_DIR=%USERPROFILE%\tools\alterac-ai"
powershell -NoProfile -Command "irm https://alterac.ai/install.ps1 | iex"

The settings remain in that Command Prompt session. Clear them with set "ALTERAC_AI_NO_MODIFY_PATH=" and set "ALTERAC_AI_INSTALL_DIR=", or close the terminal.

If you set ALTERAC_AI_NO_MODIFY_PATH=1, add the chosen installation directory to PATH yourself. For the example Unix folder, run export PATH="$HOME/tools/alterac-ai:$PATH" to use it in the current terminal, and add that line to your shell's configuration file for future terminals. Use the shell files listed above for Bash or Zsh.

On Windows, add the chosen folder to your user Path through Environment Variables, then open a new terminal. For the example folder, $env:Path = "$env:USERPROFILE\tools\alterac-ai;$env:Path" makes it available immediately in the current PowerShell session only; it does not save user PATH. Substitute your installation directory in these steps, including the default folder if you did not customize it.

The available builds are macOS ARM64 (Apple silicon) and x64 (Intel), Linux ARM64 and x64, and Windows x64. WSL uses the matching Linux build. Linux requires glibc; musl systems such as Alpine are unsupported. There is no native Windows Arm64 build; Windows Arm64 uses the x64 build through emulation in a 64-bit PowerShell process.

The macOS and Windows binaries are unsigned. Security prompts depend on how the executable reaches your device and your organization's policy. The installer verifies the archive; it does not disable operating-system protections.

The recorded macOS script-install check launched without a Gatekeeper prompt or quarantine attribute. Browser-downloaded archives may receive a security prompt; managed-device policy may also block execution. If macOS blocks the first launch, open System Settings, then Privacy & Security, and use Open Anyway for alterac-ai only if your organization's policy allows it. On Windows, if SmartScreen shows Windows protected your PC, select More info, confirm the app is alterac-ai.exe, and select Run anyway only if allowed. Do not disable Gatekeeper or SmartScreen. Contact your organization if a managed device prevents the exception.

Before removing the executable, run:

alterac-ai logout

This removes stored authentication for the selected service. Then remove ~/.local/bin/alterac-ai on macOS, Linux, or WSL, or %USERPROFILE%\.local\bin\alterac-ai.exe on Windows. If you chose another directory, remove the binary there instead.

Remove the marked PATH line the script added to your shell file, or remove its directory from your Windows user PATH, if no other tools use that entry. Open a new terminal afterward.

Optionally remove the alterac-ai user application-data folder after signing out of every service you used: ~/Library/Application Support/alterac-ai on macOS, $XDG_CONFIG_HOME/alterac-ai (or ~/.config/alterac-ai) on Linux, and %APPDATA%\alterac-ai on Windows. Release-check cache data lives in ~/Library/Application Support/alterac-ai/cli on macOS, $XDG_CACHE_HOME/alterac-ai (or ~/.cache/alterac-ai) on Linux, and %LOCALAPPDATA%\alterac-ai\cli on Windows. Repository .alterac-ai files are separate; keep them if you plan to reconnect the repository.

If a new terminal cannot find alterac-ai, check the PATH change printed by the installer. For checksum failures, unsupported platforms, a locked Windows executable, or a sudo refusal, see Fix repository setup.

Can't run the install script? Download the CLI manually.