Fix repository setup

Use this page when repository commands cannot find valid .alterac-ai setup, select the wrong project, or report that managed guidance needs an update.

Open a terminal in the intended repository and run:

alterac-ai init

Sign in if prompted, select the project that should own this repository's work, choose the requested trust setting and managed instruction-file option, and let initialization finish.

The expected result is a local .alterac-ai configuration and a confirmation of the selected project. Do not copy .alterac-ai from another repository, because its selected project and local trust choices may not apply here.

Run alterac-ai init again from this repository and select an available project. If the intended project is absent, confirm that you signed in with the intended account and that its access is still active. Do not treat a missing project as proof that it exists or that another account can access it.

The expected result is a confirmation for the intended project. Restart any local listener after changing the selection.

Run:

alterac-ai docs-update

This refreshes the CLI-managed guidance for the existing setup. If docs-update says the setup lacks a required selection, rerun alterac-ai init and choose the current options.

The expected result is an up-to-date managed bundle without replacing your unrelated repository files. For a changed coding-agent command, review the local trust prompt before approving it.

A linked worktree contains tracked files from Git, not ignored dependencies, .env files, secrets, build output, or other machine-local state from the retained checkout. Use the repository's documented, idempotent setup path inside the task worktree. Do not solve the problem by committing secrets or copying unexplained machine state.

Run alterac.ai CLI commands from the retained initialized checkout, and pass absolute paths when a command needs a file produced in the task worktree. See prepare repositories for task worktrees for setup, hooks, parallel resources, and cleanup ownership.

Open Install the CLI and run the command for your shell. After installation, open a new terminal and confirm alterac-ai --version matches the installer's reported version. Then return to alterac-ai init.

Open a new terminal so it receives the updated PATH. On macOS and Linux, check which shell file the installer reported: ~/.zshrc, ~/.bash_profile, or ~/.bashrc. Make sure your terminal uses that shell and reads that file. Other shells need the export line printed by the installer.

On Windows, check that the installed folder appears in your user PATH, then restart the terminal. If you set ALTERAC_AI_NO_MODIFY_PATH=1, add the printed folder yourself. If an older version still runs, check for another alterac-ai earlier in PATH.

• Checksum or size mismatch: stop and retry after checking your connection. Do not run the unverified binary. If the error persists, contact support.
• Unsupported platform: use a supported macOS or glibc Linux ARM64/x64 system, or Windows x64. Alpine and other musl Linux distributions are unsupported. Windows Arm64 uses x64 emulation; run a 64-bit PowerShell process.
• Locked alterac-ai.exe: stop the running CLI or listener that holds the executable, then rerun the installer.
• sudo refusal: rerun as your normal user without sudo; installation needs no administrator access.

If scripts are blocked in your environment, download the CLI manually. If that page cannot load trusted archive links, check your connection and select Retry manifest loading. Do not invent an archive URL.

Open Install the CLI and rerun the install command. The original command still runs normally; the CLI does not update itself.

Open a new terminal and run alterac-ai --version. The expected result is the version reported by the installer.

For sign-in failures, see Fix CLI login. For listening and local approval problems, see Fix the local listener.