> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Scripts, CI and coding agents

> Run the Mutagent CLI without a person at the keyboard: sign in with an API key, read --json output, branch on exit codes, and let a coding agent drive it.

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 every command prints one JSON object you can parse.
3. Check the exit code, so the script knows whether the command worked.

## A CI job

```bash theme={null}
export MUTAGENT_API_KEY=<api-key>          # from your CI secret store
export MUTAGENT_WORKSPACE_ID=<workspace-id>

mutagent workspaces current --json         # exit 0: the key works and the workspace is set
printf 'GITHUB_TOKEN=%s\n' "$GITHUB_TOKEN" > .env.secrets
mutagent env set ci DATABASE_URL="$DATABASE_URL" --secrets-from-file .env.secrets --json
rm .env.secrets
mutagent helix agent @<agent-slug> --env ci -p "Write release notes for $GIT_TAG." > notes.md
```

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](/quickstart/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` also names
the slot: `<agent-slug>` must be deployed with `--env ci`. See [Managed agents](/cli/commands/agent).

`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](/helix/cloud/agent-runs#output).

## Read --json output

A successful command prints its result as one JSON object on stdout:

```bash theme={null}
mutagent env list --json
```

```json theme={null}
{
  "success": true,
  "environments": [],
  "count": 0
}
```

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:

```bash theme={null}
count=$(mutagent env list --json | jq '.count')
```

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](/cli/errors).

## Check the exit code

```bash theme={null}
if ! mutagent workspaces current --json > whoami.json; then
  echo "Not ready: $(jq -r '.error' whoami.json)"
  echo "Fix: $(jq -r '.suggestedAction' whoami.json)"
  exit 1
fi
```

`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](/cli/errors#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` 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](/cli/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:

| Field | What it is |
| - | - |
| `_directive.renderedCard` | A status card for the agent to show you as it is. |
| `_directive.instruction` | What to do next. |
| `_directive.next` | Suggested follow-up commands. |
| `_links` | Links to the web app and the API for the result. |
| `_compat` | `cliVersion`, `skillVersion` and `skillMinCliVersion`, to check the installed skill matches the CLI. |

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](/cli/commands/login).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.