Skip to main content
The CLI works the same way from a script, a CI job or a coding agent such as Claude Code or Codex as it does from your terminal. Three things make that reliable:
  1. Sign in with an API key in MUTAGENT_API_KEY, so nothing opens a browser.
  2. Add --json, so each command prints JSON you can parse: one object, except login --browser, which prints one object per line. A mutagent helix run uses --mode json instead.
  3. Check the exit code, so the script knows whether the command worked.

​
A CI job

With MUTAGENT_API_KEY set, no command asks you to sign in. A key that mutagent login did not save has no saved workspace, so set MUTAGENT_WORKSPACE_ID (or pass --workspace on each command). See API keys for which key to use. Secrets go in a file passed with --secrets-from-file, so they stay off the command line. For a managed agent, --env ci also picks which deployment of the agent runs (its slot), so <agent-slug> must have been deployed with --env ci. See Managed agents. mutagent helix prints Helix’s answer on stdout, so it can go straight into a file. --json does not change a Helix run’s output; use --mode json for Helix’s events. See Run a task.

​
Read —json output

A successful command prints its result as one JSON object on stdout:
The fields depend on the command. Each command’s --help says what its --json output contains. Messages meant for a person, such as progress lines and status cards, go to stderr, so stdout stays parseable:
A failed command prints an object with success: false, a stable code, a suggestedAction and _agentGuidance. success is true exactly when the exit code is 0. See Errors and exit codes.

​
Check the exit code

0 is success. 1 is a failure, 2 means the API key expired or is not valid, and 3 means you are not signed in or no workspace is selected. See the table of exit codes.

​
No questions asked

The CLI never waits for an answer when no person can give one. Under --non-interactive, with CI=true, or when stdin is not a terminal:
  • Sign-in uses the browser flow without asking which method to use, and only prints the URL. With --json it also needs --browser. Set MUTAGENT_API_KEY instead, so no browser is needed.
  • A command that would copy or write after showing a plan, such as mutagent providers mirror, stops with exit code 1 and writes nothing until you pass --yes.
  • A command that deletes something refuses without --force. It never asks.
  • mutagent triage file (files a problem report about an agent in your workspace; see Reports, findings and triage) prints a preview, sends nothing, and exits 0 with sent: false until you pass --yes.

​
Coding agents

A coding agent can run the CLI for you. Give it Installation for the setup. Tell it to:
  • install the CLI skill first with mutagent skills install (it writes .claude/skills/mutagent-cli/SKILL.md), which holds the full workflows,
  • pass --json to every command, except a mutagent helix run, whose output is Helix’s own,
  • run mutagent <command> --help before it uses a command for the first time,
  • confirm with you before any command that deletes something or writes a credential.
Each command’s --help ends with an “AI Agent Directive” section: short rules written for coding agents, such as which command to run first. A --json result can also carry: Which field says what to run next: after a success, read _directive.next (a mutagent gateway command puts the same list in a top-level next array). After a failure, read _agentGuidance.fix and suggestedAction. To sign in from a coding agent, run mutagent login --browser --json. The CLI prints a URL and waits up to 5 minutes. The first line of output is {"event":"auth_url","url":"…","expiresAt":"…"}; the result follows on the next line. The agent shows you the URL verbatim, and you open it and approve. With a key, the agent runs MUTAGENT_API_KEY=<api-key> mutagent login --json instead. Then it checks the workspace with mutagent workspaces current --json. See Sign in.