Docs › CLI › CLI reference

CLI reference

Every astracode-agent subcommand and flag, environment variable, file, JSON shape and exit code.

On this page

Synopsis

astracode-agent --help

astracode-agent ["<first request>"]          a conversation in this folder
astracode-agent --continue | --resume       pick up an earlier one
astracode-agent -p "<prompt>" [options]     one task, then exit
astracode-agent login [--no-browser] [--code]
astracode-agent logout
astracode-agent status
astracode-agent update
astracode-agent undo [<run>] [--list] [--restore <id>] [--cwd <dir>]
astracode-agent review [--base <ref>] [--output-format text|json] [--max-steps <n>] [--cwd <dir>] [--trust] [-v]
astracode-agent acp [--agents <json|file>] [--agent <name>] [--allow-agent-mcp] [--trust]
astracode-agent plugin <verb> ...
astracode-agent --version | --help

Unknown options are refused: the CLI prints astracode-agent: and the problem, then the usage, and exits 2. An unexpected error prints its message and (set ASTRACODE_DEBUG=1 for the details), and exits 1.

Subcommands

CommandWhat it doesExit codes
(none)A conversation: full screen at a terminal, the line session otherwise. Takes an optional first request, -c/--continue, -r/--resume, --cwd, --agents, --agent, --trust, -v. The -p-only options are refused: --X applies to -p runs. See The conversation.0 on leaving; 1 when the first run was not finished; 2 when it cannot open
-p, --printOne task. See Scripts and CI.0, 1, 2, 130
loginSign in through the browser. --no-browser prints the link without opening a browser; the link only works on this machine. --code signs in with a code pasted from a browser anywhere, and is used automatically when SSH_CONNECTION or SSH_TTY is set. See Sign in.0 signed in; 1 failed; 130 cancelled
logoutRemoves the saved session.0
statusWho you are signed in as, or that the API key is in use. May renew the session.0 signed in; 1 not
updateInstalls the latest version (install script), or prints the Homebrew or npm command.0, 1, or the installer's code
undoPuts back a run's changes. --list shows ten runs, <run> picks one, --restore <id> takes an undo back, --cwd picks the folder. A run with --list or --restore, or both of those, is a usage error.0, 1
reviewReviews the branch. See Reviewing a branch.0, 1, 2, 130
acpServes the Agent Client Protocol on stdin and stdout. See Zed and JetBrains.
pluginManages plugins. See Plugins.0 done; 1 refused or failed; 2 usage

There is no mcp subcommand: MCP servers go in the settings file, and /mcp lists them in a conversation.

Options for -p

OptionDefaultAlso on
--mode agent|planagent
--output-format text|json|stream-jsontextreview (text or json)
--permissions read-only|auto|fullread-only
--max-steps <n>150 (60 for review)review
--cwd <dir>the current folderconversation, review, undo
--agents <json or file>conversation, acp
--agent <name>conversation, acp
--allow-agent-mcpoffacp
--report-to <url>
--trustno effect with -pconversation, acp, review
-v, --verboseoffconversation, review

--agents takes JSON, or a file holding it, in Claude Code's shape: {"<name>": {"description": "...", "prompt": "...", "tools": [...], "model": "fast"}}. model is a tier: inherit, fast or strong. Errors (exit 2) say what is wrong: neither JSON nor a readable file, not an object of agents, a bad name, a missing description or prompt, or for --agent a name that does not exist, with the list of agents.

Environment variables

VariableEffect
ASTRACODE_API_KEYAn ac_live_ key from your dashboard. Used instead of a saved session by -p, review, acp and status; the conversation asks once per key.
ASTRACODE_GATEWAY_URLThe gateway to use. Default https://api.astracode.io.
ASTRACODE_TRUSTExactly 1 trusts the folder, as --trust does.
ASTRACODE_CONFIG_DIRThe config folder. Setting it also keeps the session in a file there instead of the macOS Keychain.
XDG_CONFIG_HOMEThe base of the config folder when ASTRACODE_CONFIG_DIR is not set.
ASTRACODE_THEMEForce a theme: dark, light, dark-cb, light-cb, dark-ansi or light-ansi.
NO_COLOR, FORCE_COLOR, COLORTERM, TERM, COLORFGBGColour detection, as usual.
ASTRACODE_NO_ANIMATIONTurn off the spinner and animation.
ASTRACODE_DEBUGPrint the full details of an unexpected error.
ASTRACODE_UPDATE_CHECK0 turns the update check off; 1 checks even when stderr is not a terminal or CI is set.
CISet: no update check, and requests are marked as coming from CI.
SSH_CONNECTION, SSH_TTYSet: login signs in with a pasted code.
ASTRACODE_DOWNLOAD_BASEWhere the installer and update download from. Default https://astracode.io/downloads/cli.
ASTRACODE_INSTALL_URLThe installer update runs.
ASTRACODE_NPM_REGISTRYThe registry the update check asks, for an npm install.
ASTRACODE_VERSIONInstaller: the version to install.
ASTRACODE_BIN_DIRInstaller: where the command goes. Default ~/.local/bin, or %USERPROFILE%\.local\bin on Windows.
ASTRACODE_DATA_DIRInstall script: where versions are kept. Default ~/.local/share/astracode-agent.
ASTRACODE_PLUGINS_DIRWhere plugins are kept. Default ~/.astracode/plugins.
ASTRACODE_GITThe git program used to fetch plugins.
VISUAL, EDITORThe editor Ctrl-G opens.
SHELLThe shell ! runs in.
PATHWhere rg and git are found.

Files

The config folder is $ASTRACODE_CONFIG_DIR, else $XDG_CONFIG_HOME/astracode, else ~/.config/astracode, on every system: on Windows that is %USERPROFILE%\.config\astracode. It is private to you.

FileWhat it holds
settings.jsonYour settings: mcp.servers, theme, trustedFolders, onboarded, apiKeyChoice, and any other AstraCode setting the agent reads, with or without the astracode. prefix. Never read from a project.
credentials.jsonThe session, readable only by you, on Linux and Windows, or anywhere ASTRACODE_CONFIG_DIR is set. On macOS otherwise the session is in the Keychain as AstraCode CLI.
secrets.jsonSensitive plugin options, where there is no Keychain. On macOS they are in the Keychain as AstraCode CLI secrets.
update-check.jsonWhen the update check last ran (checked at most daily).
agent-mcp.jsonYour answers about agent files' MCP servers.
history/What you typed, per folder, for Up and Ctrl-R.
sessions/Saved conversations, per folder.
checkpoints/Each folder's checkpoints, for undo and /rewind.
ElsewhereWhat it holds
~/.astracode/memoriesMemories, shared with the editor.
~/.astracode/pluginsInstalled plugins, shared with the editor.
.astracode/agents, .claude/agents, ~/.astracode/agents, ~/.claude/agentsAgent definitions, nearest first.
.astracode/skills, .astracode/commands, .astracode/hooks.json and the other foldersAs in the editor; see Skills and commands and Hooks.

JSON shapes

CommandShape
-p --output-format json{type, ok, end, summary, filesChanged[{path, created, added, removed}], denied[{description, warning?}], steps, planSlug, durationMs, tasks[], runId?}; on an early failure {type, ok: false, error}. Fields: Scripts and CI.
-p --output-format stream-jsonOne agent event per line, then {type: "denied", ...} for each refusal and the final result.
review --output-format json{type, ok, end?, base?, files[], findings[{file, line, summary, failure, severity, category?}], reported, truncated, summary?, error?, steps?}. Fields: Reviewing a branch.
plugin list --jsonThe installed plugins, or with --available the marketplaces' listings.
--report-to eventsPOST <url>/events with {seq, type, data}, type started, step, tool, report or ended.

Exit codes

Code-previewOthers
0FinishedFinished (with or without findings)Done
1Not finished, or the gateway refusedNot finished, no findings reported, or the gateway refusedstatus not signed in; login failed; undo nothing to undo or failed; plugin refused; conversation first run not finished
2Usage error, not signed in, bad --cwd, bad --agents or --agent, empty stdin promptNot in a git repository, no common ancestor, no base found, usage error, not signed inUsage errors
130InterruptedInterruptedlogin cancelled

← Zed and JetBrains Usage and limits →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference