Docs › Troubleshooting › CLI problems

CLI problems

Fix sign-in, trust, network, search, undo, update and plugin problems with astracode-agent.

On this page

Errors from astracode-agent start with astracode-agent:. For the full technical detail of an unexpected error, run the command again with ASTRACODE_DEBUG=1 set. The commands and flags are on the CLI reference.

Not signed in

Not signed in. Run astracode-agent login, or set ASTRACODE_API_KEY. With -p and review the exit code is 2.

  1. Run astracode-agent login and approve in the browser.
  2. In CI, set ASTRACODE_API_KEY instead. See Scripts and CI.
  3. Check with astracode-agent status.

Signing in over SSH or in a container

Cause: the browser hands sign-in back to 127.0.0.1 on the machine that opened it, which over SSH or in a container is the wrong machine.

  1. Run astracode-agent login --code. Over SSH this is chosen for you.
  2. Open the printed link in a browser on any device and approve.
  3. Copy the code the page shows and paste it at the Code: prompt.
  4. The CLI says Signed in. and where the session is saved.

If the code is refused, the CLI adds (a code works once, for five minutes). Run astracode-agent login --code again and paste the new code within five minutes. For CI, use ASTRACODE_API_KEY instead.

Sign-in timed out, was declined, or was cancelled

sign-in timed out waiting for the browser, sign-in was declined in the browser, sign-in was cancelled or sign-in was not completed, each followed by Run astracode-agent login to try again.

  1. Run astracode-agent login again and approve within 30 minutes.
  2. If the browser cannot reach this machine, use login --code.

Your session has expired

Your session has expired. or Your session has ended. A session lasts 36 hours and is renewed as you use the CLI. Run astracode-agent login.

A run that stops with You are signed out has the same fix: run astracode-agent login, or check that ASTRACODE_API_KEY holds a current key.

Could not save to the Keychain

could not save to the Keychain: followed by a reason, on macOS.

Another sign-in is already waiting

Finish or close the sign-in already open in your browser, then try again.

Unable to connect to AstraCode

On first run: Could not reach the gateway, Check your internet connection, a proxy or VPN, and try again. During a run: Could not reach AstraCode, with the reason.

  1. Check the connection, and that a VPN or proxy allows api.astracode.io.
  2. If you use your own gateway, check ASTRACODE_GATEWAY_URL.
  3. Run the command again.

The reasons and the other gateway cards are the same as in the editor: see Usage, billing and network errors.

The folder is not trusted

Tool results say a tool is disabled in an untrusted folder, and the agent reads and answers but does not change files or run commands.

Answering No, exit to the trust question on first run quits with exit code 1. See Workspace trust.

Unknown command

Unknown command / followed by a name. Type /help for the commands in the conversation. /trust is not one of them in the full-screen conversation; see the section above.

Content search is unavailable

A tool result says content search is unavailable (ripgrep not found in this build).

  1. Install ripgrep (rg) with your package manager.
  2. Make sure rg is on your PATH, then run again.

Nothing to undo, or no run with that id

review cannot find what to compare against

MessageFix
is not inside a git repositoryRun it inside the repository, or pass --cwd.
cannot find a common ancestor of HEAD and a baseIn CI, check out with fetch-depth: 0.
could not work out what to compare against; pass --base <ref>Pass --base main, or the branch you compare with.

See Reviewing a branch.

Usage errors (exit code 2)

Update problems

Plugin was not installed

A plugin was not installed: it runs the commands above, and nobody was asked.

  1. Read the commands the plugin would run, printed above the message.
  2. Run the install again with --yes if you accept them.

A sensitive plugin option is never taken from the command line: run astracode-agent plugin config with the key and no value, and type it or pipe it in. See Plugins.

Zed or JetBrains: the agent will not change files

Cause: acp treats the folder as untrusted unless told otherwise, and in an untrusted folder edits and commands are refused outright.

See Zed and JetBrains.

← Usage, billing and network errors Settings reference →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference