Docs › CLI

AstraCode CLI

Install astracode-agent, sign in, and use the AstraCode agent in a terminal, a CI job, or Zed and JetBrains.

astracode-agent is the AstraCode agent without the editor. On its own it opens a conversation in the current folder. With -p it runs one task and exits, for scripts and CI. It runs the same agent as the editor, with AstraOne's model routing and the same approval rules, on the same account.

The command is astracode-agent because astracode already opens the editor.

Install

On macOS or Linux, arm64 or x64:

curl -fsSL https://astracode.io/install | sh

It puts a standalone binary in ~/.local/bin with Node built in. It checks the download's checksum, and on a Mac that AstraCode signed it. Nothing needs sudo.

On Windows, x64 or arm64, in PowerShell:

irm https://astracode.io/install.ps1 | iex

It puts astracode-agent.exe in %USERPROFILE%\.local\bin, checks the download's checksum, and adds that folder to your user PATH. It needs no administrator rights. $env:ASTRACODE_VERSION pins a version and $env:ASTRACODE_BIN_DIR picks another folder; the macOS and Linux installer reads the same two variables.

Or, with Homebrew on macOS or Linux:

brew install astracode-io/tap/astracode-agent

Or, anywhere with Node 20 or later:

npm install -g astracode-agent

The CLI tells you when a newer version is out. If you used the installer, astracode-agent update installs it. A Homebrew or npm copy is theirs to update, and the CLI names the command: brew upgrade astracode-agent or npm install -g astracode-agent@latest.

Sign in

• On your own machine, run astracode-agent login once. It signs you in through your browser and keeps the session, in the Keychain on macOS and in ~/.config/astracode elsewhere. Using it at least every day and a half keeps it signed in.
• Over SSH, astracode-agent login --no-browser prints the link to open on another machine instead.
• In CI, or anywhere nobody can sign in, create an API key on your dashboard and set ASTRACODE_API_KEY. A key takes precedence over a saved session, can carry its own limit, and can be revoked without signing anyone out.
• astracode-agent status says who you are signed in as, and exits 1 when nobody is. astracode-agent logout forgets the session.

The first time you run it, it checks it can reach AstraCode, asks which colour theme suits your terminal, signs you in, and asks once per folder whether you trust what is in it.

A conversation

astracode-agent
astracode-agent "why does the login test fail?"
astracode-agent --continue    # this folder's last conversation
astracode-agent --resume      # choose an earlier one

• Before it acts, it asks. Approve an edit or a command once, for the rest of the session, or say no and tell it what to do instead.
• Shift-Tab cycles three modes: ask, auto, where edits and commands run and only risky ones ask, and plan, where it reads, writes a plan and offers to build it.
• Esc stops a run and keeps what it has done. A message typed while it works reaches it at its next step.
• Every edit is shown as a diff. Ctrl-O shows a tool's full output and Ctrl-T the todo list. The footer shows the mode and how much of the context is used.
• \ then Enter, Ctrl-J or Option-Enter starts a new line. Up and Down go through history and Ctrl-R searches it. Ctrl-G opens the message in $EDITOR, and Ctrl-V pastes an image on macOS.
• @ mentions a file. !command runs in your shell and sends its output with your next message. # note remembers something about the project.

Your own commands and skills from .astracode/commands and .astracode/skills appear in the / menu. MCP servers go under mcp.servers in ~/.config/astracode/settings.json. That file is read from your home directory only, never from the project: mcp.servers names commands that run on start, and a settings file inside a repository you cloned could otherwise run anything.

One task, from a script or CI

astracode-agent -p "fix the failing test in tests/test_billing.py" --permissions auto

A `-p` run trusts the folder it runs in, as Claude Code's -p does: you chose the folder, and --permissions decides what the run may do. The project's rules, hooks, skills, commands and agents all load. A conversation, acp and review are different: there a folder is untrusted until you say otherwise, and in an untrusted folder the agent reads and answers but changes no file, runs no command and loads nothing the project carries, so a repository you just cloned cannot run a hook by being opened. Trust it with --trust for one session, with ASTRACODE_TRUST=1, or for good: the full-screen conversation asks on its first run in a folder, and /trust remembers it. review stays untrusted unless told, because a fork's pull request reaches it.

Nobody is there to approve anything, so this is decided up front:

• read-only (the default): it reads, searches and answers, and is refused every edit and every command.
• auto: it edits files and runs commands, but is still refused a command the risk check flags, such as git push or rm -rf outside the project, a request to another machine, and saving a memory.
• full: those are allowed too.

Every refused action is listed in the result, so a CI log says why nothing changed. With --output-format json the result is one object with ok, end, summary, filesChanged, denied, steps, durationMs, and runId when the run changed something.

A run that stopped short fails the job. It does not report success with an apology in the summary.

Undo a run

astracode-agent undo              # the last run in this folder
astracode-agent undo --list       # recent runs, newest first
astracode-agent undo <run>        # that one

Every run that may change files, in a conversation, with -p or over acp, takes a checkpoint before each edit and each command, kept outside the project. undo puts back what the run changed, including what its commands generated, deleted or rewrote, and leaves alone, and lists, any file that has changed again since. It prints the --restore <id> that takes the undo back. review, read-only and plan runs change nothing, so they have nothing to undo. Checkpoints need git on your PATH.

Review a branch

astracode-agent review --base main --output-format json

Reviews this branch's changes against --base, which defaults to its upstream, then the remote's default branch, then main. It is read-only, and reports only findings it can describe a concrete failure for, at most eight. With --output-format json it prints { ok, base, files, findings, ... } for a script to act on.

In Zed or a JetBrains IDE

astracode-agent acp speaks the Agent Client Protocol, so an editor that runs external agents can use AstraCode as its agent. The editor starts it; you do not run it yourself. Sign in the same way as on the command line.

Zed: add this to settings.json, then pick AstraCode in the agent panel.

{
  "agent_servers": {
    "AstraCode": {
      "type": "custom",
      "command": "astracode-agent",
      "args": ["acp"]
    }
  }
}

JetBrains: in the AI Chat tool window choose Add Custom Agent, and put this in the ~/.jetbrains/acp.json it opens. Use the full path that which astracode-agent prints.

{
  "agent_servers": {
    "AstraCode": {
      "command": "/Users/you/.local/bin/astracode-agent",
      "args": ["acp"]
    }
  }
}

The editor shows each edit as a diff and asks before the agent changes a file or runs a command. Risky commands and requests to other machines are asked about every time.

In GitHub Actions

- run: curl -fsSL https://astracode.io/install | sh
- run: ~/.local/bin/astracode-agent -p "Fix the failing test in tests/test_billing.py" --permissions auto --output-format json
  env:
    ASTRACODE_API_KEY: ${{ secrets.ASTRACODE_API_KEY }}

Let the agent make the edits, and let the workflow's own steps commit, push and comment. The agent refuses git push under auto for exactly that reason.

Reporting progress

--report-to <url> posts the run's progress to <url>/events as it goes, one small JSON event at a time with the run's key as the bearer: started, each step, each tool by name, the final report, and ended with the outcome. Never a tool's input or output, a file, a path or a command. Delivery is retried briefly and never slows or fails the run. It is how a remote agent reports to its card in the editor.

What needs the editor

Language-server lookups, live diagnostics and the code index need the editor, in every way of running the CLI. MCP servers, memories and rewinding a turn are part of the conversation. Content search uses rg from your PATH, so install ripgrep; GitHub's runners already have it.

All documentation

Get started

• Quickstart
• Install AstraCode
• The chat panel

Agent

• Agent overview
• Approvals and permissions
• Plan mode
• What the agent can do
• Running commands
• Browser tools
• Checkpoints and undo
• Infrastructure as code
• Running several agents at once
• Subagents and background tasks
• Remote agents in GitHub Actions

Context

• How context works
• Rules
• Memories

Workspaces

• Workspaces
• Working across several repositories

Connectors

• Connectors (MCP servers)
• Use AstraCode from Claude, ChatGPT and other apps

Extending AstraCode

• Plugins and skills
• Plugins
• Skills
• Hooks
• Dictation

CLI

• AstraCode CLI

Reference

• Settings reference
• Keyboard shortcuts
• Models