Docs › CLI › Scripts and CI

Scripts and CI

Run one task with -p: permissions, trust, output formats, JSON fields, exit codes, undo, GitHub Actions and progress reporting.

On this page

astracode-agent -p runs one task and exits. Nobody is there to approve anything, so what the agent may do is decided up front with --permissions, and every refused action is listed in the result.

Terminal

astracode-agent -p "fix the failing test in tests/test_billing.py" --permissions auto
git diff | astracode-agent -p - --output-format json     # the task from stdin

Options

OptionDefaultWhat it does
-p, --print <prompt>The task. - reads it from stdin.
--mode agent|planagentagent makes the change; plan only writes a plan.
--permissions read-only|auto|fullread-onlyWhat the agent may do (below).
--output-format text|json|stream-jsontextThe final answer, one result object, or one event per line.
--max-steps <n>150The step limit for the run.
--cwd <dir>the current folderThe workspace.
--agents <json or file>Agent definitions for this run, in Claude Code's shape. They win over .astracode/agents and .claude/agents.
--agent <name>Run the whole task as that agent: its prompt, tools and model tier.
--allow-agent-mcpoffLet the project's agent files start the MCP servers they declare, for this run only.
--report-to <url>Post the run's progress as it goes (below).
--trustAccepted and changes nothing: a -p run already trusts its folder.
-v, --verboseoffThe agent's own log, on stderr.

--continue and --resume open a conversation, so they are refused with -p. An empty prompt on stdin is refused with exit code 2.

Permissions

LevelWhat the agent may do
read-only (default)Read, search and answer. Every edit and command is refused.
autoEdit files and run commands. Still refused: a command the risk check flags (such as git push or rm -rf outside the project), a request off this machine, and saving a memory: the things the editor confirms even when it never asks.
fullThose too.

In text mode, refusals are listed on stderr after the answer: N action(s) denied under --permissions auto: and one line each. In JSON they are in denied. A CI log therefore says why nothing changed.

Trust

A -p run trusts the folder it runs in: 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; see Workspace trust. -p starts no MCP servers from your settings file, and a project's agent files start theirs only with --allow-agent-mcp; your own agent files under ~ start theirs.

Output

text

The agent's final answer on stdout. Reports from background agents it never read follow, each headed [background agent <id> (<type>) "<title>" <state>]. On stderr: to undo this run: astracode-agent undo <runId> when it changed something, and the refused actions.

json

One object when the run ends:

--output-format json

{
  "type": "result",
  "ok": true,
  "end": "finished",
  "summary": "Fixed the rounding in invoice totals; the test passes.",
  "filesChanged": [{ "path": "src/billing.py", "created": false, "added": 3, "removed": 1 }],
  "denied": [{ "description": "run git push", "warning": "..." }],
  "steps": 14,
  "planSlug": null,
  "durationMs": 48210,
  "tasks": [],
  "runId": "r-20261114-1a2b"
}
FieldMeaning
typeAlways "result".
oktrue when the exit code is 0.
endHow it ended: finished, stopped, looped, ceiling (the step limit) or errored.
summaryThe final answer.
filesChangedEach file: path, created, lines added and removed.
deniedEach refused action: description, and warning when there was one.
stepsSteps taken.
planSlugThe plan written, in --mode plan.
durationMsHow long it took.
tasksEvery background task: its id, kind, title, state, start and end, and for an agent its type, steps, files changed and report.
runIdPresent only when checkpoints recorded changes; pass it to undo.

If the run fails before it can produce a result, the object is just {"type": "result", "ok": false, "error": "..."}.

stream-json

One JSON object per line as the run goes: every event the agent emits except the streaming text and thinking fragments. Among them toolCall, toolResult (with a fileChange for edits), text, thinking, progress, todos, plan, context, compacted, and agentStarted, agentProgress and agentEnded for subagents. Any event may carry agentId and parentAgentId. A refusal is {"type": "denied", ...}, and the last line is the result object above.

Exit codes

CodeMeaning
0The agent finished.
1It did not finish (the step limit, a loop, an error), or the gateway refused the request.
2A usage error; not signed in; --cwd is not a folder; a bad --agents or --agent; or an empty prompt on stdin.
130Interrupted. A second Ctrl-C exits at once.

A run that stopped short fails the job: it does not report success with an apology in the summary. Background agents are waited for before the CLI exits.

Undo a run

Terminal

astracode-agent undo                   # the last run in this folder not yet undone
astracode-agent undo --list            # the last ten runs, newest first
astracode-agent undo <run>             # that one
astracode-agent undo --restore <id>    # take an undo back

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 in the CLI's config folder. undo puts back what the run changed, including what its commands created, deleted or rewrote, and lists each file it restored, removed or reverted. It leaves alone any file changed again since, and says Left alone, changed since: with their names. It ends with the --restore command that takes the undo itself back. undo needs no sign-in, accepts --cwd, and needs git on your PATH. Read-only, plan and review runs change nothing, so they have nothing to undo.

In GitHub Actions

  1. Create an API key on your dashboard under API & SSH keys, and add it to the repository as a secret named ASTRACODE_API_KEY.
  2. Add a step that installs the CLI, and one that runs the task with that secret in its environment.
  3. Let the workflow's own steps commit, push and comment. The agent refuses git push under auto for exactly that reason.

.github/workflows/fix.yml

- uses: actions/checkout@v4
- 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 > result.json
  env:
    ASTRACODE_API_KEY: ${{ secrets.ASTRACODE_API_KEY }}

No update notice is printed when CI is set. To have AstraCode run the agent in your repository's Actions for you, from the editor or from another app, see Remote agents in GitHub Actions. To review pull requests, see Reviewing a branch.

Reporting progress

--report-to <url> posts the run's progress to <url>/events as it goes, one small JSON event per request, {seq, type, data}, with the run's credential as the bearer token. The types are started, each step, each tool by name, the final report (up to 20,000 characters), and ended with the outcome. Never a tool's input or output, a file, a path or a command.

If something goes wrong

← The conversation Reviewing a branch →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference