> ## 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.

# Commands

> The Mutagent CLI commands, grouped by what they are for, and the flags that work with every command.

Each command group has its own page. Run `mutagent <command> --help` to see the same information in
your terminal. This page lists every command group in `@mutagent/cli` 0.2.207: `agent`, `architech`,
`artifacts`, `auth`, `config`, `env`, `factory`, `feedback`, `findings`, `gateway`, `helix`, `hooks`, `inbox`, `init`,
`install`, `integrations`, `login`, `providers`, `reports`, `sandbox`, `skills`, `traces`, `triage`,
`usage` and `workspaces` (also `workspace`).

Before you run any of them, install the CLI, sign in and choose a workspace: see
[Installation](https://docs.mutagent.io/cli/installation.md).

When a command fails, see [Errors and exit codes](https://docs.mutagent.io/cli/errors.md). To run commands from a script, CI or
a coding agent, see [Scripts, CI and coding agents](https://docs.mutagent.io/cli/json.md).

## Account

Sign in, choose the workspace commands act on, and see your account.

| Command | What it does |
| - | - |
| [`mutagent login`](https://docs.mutagent.io/cli/commands/login#mutagent-login) | Sign in through the browser or with an API key, or create an account. `mutagent auth login` is the same command. |
| [`mutagent auth status`](https://docs.mutagent.io/cli/commands/login#mutagent-auth-status) | Check that the server accepts your key; show the endpoint and the configured workspace and organization. |
| [`mutagent auth logout`](https://docs.mutagent.io/cli/commands/login#mutagent-auth-logout) | Remove the stored credentials from this machine. |
| [`mutagent workspaces list`](https://docs.mutagent.io/cli/commands/login#mutagent-workspaces-list) | List the workspaces you can use. |
| [`mutagent workspaces use`](https://docs.mutagent.io/cli/commands/login#mutagent-workspaces-use) | Select the workspace every later command works in. |
| [`mutagent workspaces current`](https://docs.mutagent.io/cli/commands/login#mutagent-workspaces-current) | Show the key's scope, organization and workspace. |
| [`mutagent workspaces get`](https://docs.mutagent.io/cli/commands/login#mutagent-workspaces-get) | Show one workspace. |
| [`mutagent config set workspace`](https://docs.mutagent.io/cli/commands/login#mutagent-workspaces-use) | The same as `mutagent workspaces use`. |
| [`mutagent config set org`](https://docs.mutagent.io/cli/commands/login#mutagent-config-set-org) | Confirm the organization of your key. |
| [`mutagent config get`](https://docs.mutagent.io/cli/commands/login#mutagent-config-get) | Read one setting. |
| [`mutagent config list`](https://docs.mutagent.io/cli/commands/login#mutagent-config-list) | Show every setting. |
| [`mutagent usage`](https://docs.mutagent.io/cli/commands/account#mutagent-usage) | Count the workspace's LLM providers and the workspaces you can see. |
| [`mutagent feedback send`](https://docs.mutagent.io/cli/commands/account#mutagent-feedback-send) | Send feedback to the Mutagent team. |

## Workspace

Store the model keys and the variables and secrets that cloud sessions use.

| Command | What it does |
| - | - |
| [`mutagent providers mirror`](https://docs.mutagent.io/cli/commands/providers#mutagent-providers-mirror) | Copy the LLM providers from your local Helix setup into the workspace. |
| [`mutagent providers add`](https://docs.mutagent.io/cli/commands/providers#mutagent-providers-add) | Add an LLM provider after testing its key. |
| [`mutagent providers list`](https://docs.mutagent.io/cli/commands/providers#mutagent-providers-list) | List the workspace's LLM providers. |
| [`mutagent providers get`](https://docs.mutagent.io/cli/commands/providers#mutagent-providers-get) | Show one LLM provider, with its key masked. |
| [`mutagent providers test`](https://docs.mutagent.io/cli/commands/providers#mutagent-providers-test) | Test an LLM provider's saved key again. |
| [`mutagent providers update`](https://docs.mutagent.io/cli/commands/providers#mutagent-providers-update) | Change an LLM provider. |
| [`mutagent providers delete`](https://docs.mutagent.io/cli/commands/providers#mutagent-providers-delete) | Remove an LLM provider. |
| [`mutagent env set`](https://docs.mutagent.io/cli/commands/env#mutagent-env-set) | Create an Environment, or add entries to one. |
| [`mutagent env list`](https://docs.mutagent.io/cli/commands/env#mutagent-env-list) | List the workspace's Environments. |
| [`mutagent env show`](https://docs.mutagent.io/cli/commands/env#mutagent-env-show) | List one Environment's entry names and value fingerprints. |
| [`mutagent env unset`](https://docs.mutagent.io/cli/commands/env#mutagent-env-unset) | Remove entries from an Environment. |
| [`mutagent env delete`](https://docs.mutagent.io/cli/commands/env#mutagent-env-delete) | Delete an Environment and its secrets. |

## Helix

Run Helix and your own agents in cloud sandboxes, and work with the sessions they start.

| Command | What it does |
| - | - |
| [`mutagent helix`](https://docs.mutagent.io/cli/commands/helix#mutagent-helix) | Run the full Helix session in a cloud sandbox, with the five stages of the agentic development lifecycle (ADLC): Spec, Build, Evaluate, Diagnose, Optimize. |
| [`mutagent helix --prime`](https://docs.mutagent.io/cli/commands/helix) | Run Helix in Prime, the experimental code-first mode, in a cloud sandbox. |
| [`mutagent helix agent`](https://docs.mutagent.io/cli/commands/helix#mutagent-helix-agent) | Run your own agent definition in a cloud sandbox. |
| [`mutagent helix session list`](https://docs.mutagent.io/cli/commands/helix-session#mutagent-helix-session-list) | List the workspace's Helix sessions. |
| [`mutagent helix session attach`](https://docs.mutagent.io/cli/commands/helix-session#mutagent-helix-session-attach) | Watch a session's output. |
| [`mutagent helix session send`](https://docs.mutagent.io/cli/commands/helix-session#mutagent-helix-session-send) | Send one command into a session. |
| [`mutagent helix session signal`](https://docs.mutagent.io/cli/commands/helix-session#mutagent-helix-session-signal) | Stop a session with SIGINT or SIGTERM; its sandbox stays up. Needs `--force`. |
| [`mutagent helix session close-input`](https://docs.mutagent.io/cli/commands/helix-session#mutagent-helix-session-close-input) | Close a session's input (end of stdin). |
| [`mutagent helix session checkpoint`](https://docs.mutagent.io/cli/commands/helix-session#mutagent-helix-session-checkpoint) | Save a checkpoint of a session now. |
| [`mutagent helix session checkpoints`](https://docs.mutagent.io/cli/commands/helix-session#mutagent-helix-session-checkpoints) | List a sandbox's checkpoints. |
| [`mutagent helix session restore`](https://docs.mutagent.io/cli/commands/helix-session#mutagent-helix-session-restore) | Restore a sandbox from a checkpoint and continue the conversation. |
| [`mutagent helix session end`](https://docs.mutagent.io/cli/commands/helix-session#mutagent-helix-session-end) | End a session by its `hs1_` id and remove its sandbox. Needs `--force`. |
| [`mutagent helix access`](https://docs.mutagent.io/cli/commands/helix#mutagent-helix-access) | Check whether your account may use cloud sandboxes, and why not. |
| [`mutagent sandbox providers`](https://docs.mutagent.io/cli/commands/sandbox#mutagent-sandbox-providers) | List the sandbox providers a run can name. |
| [`mutagent sandbox presets`](https://docs.mutagent.io/cli/commands/sandbox#mutagent-sandbox-presets) | List the presets a run can name. |
| [`mutagent helix models`](https://docs.mutagent.io/cli/commands/helix-models#mutagent-helix-models) | List the models cloud sessions can use. |
| [`mutagent helix models default`](https://docs.mutagent.io/cli/commands/helix-models#mutagent-helix-models-default) | Set the workspace default model and its fallbacks. |
| [`mutagent helix version`](https://docs.mutagent.io/cli/commands/helix-diagnostics#mutagent-helix-version) | Show the CLI version and the Helix version cloud sandboxes run. |
| [`mutagent helix doctor`](https://docs.mutagent.io/cli/commands/helix-diagnostics#mutagent-helix-doctor) | Run Helix's diagnostics in a new cloud sandbox. |
| [`mutagent helix smoke`](https://docs.mutagent.io/cli/commands/helix-diagnostics#mutagent-helix-smoke) | Run Helix's smoke test in a new cloud sandbox. |
| [`mutagent helix update`](https://docs.mutagent.io/cli/commands/helix-diagnostics#mutagent-helix-update) | Not available in the cloud. |
| [`mutagent agent check`](https://docs.mutagent.io/cli/commands/agent#mutagent-agent-check) | Compile and validate an agent folder. |
| [`mutagent agent pack`](https://docs.mutagent.io/cli/commands/agent#mutagent-agent-pack) | Write an agent's package archive and print its digests. |
| [`mutagent agent deploy`](https://docs.mutagent.io/cli/commands/agent#mutagent-agent-deploy) | Upload an agent as a revision and activate it. |
| [`mutagent agent activate`](https://docs.mutagent.io/cli/commands/agent#mutagent-agent-activate) | Make a revision the slot's active revision. |
| [`mutagent agent list`](https://docs.mutagent.io/cli/commands/agent#mutagent-agent-list) | List the workspace's agents. |
| [`mutagent agent inspect`](https://docs.mutagent.io/cli/commands/agent#mutagent-agent-inspect) | Show an agent's revisions and live sessions. |
| [`mutagent agent retire`](https://docs.mutagent.io/cli/commands/agent#mutagent-agent-retire) | Disable a slot so it takes no new runs. |
| [`mutagent agent run`](https://docs.mutagent.io/cli/commands/agent#mutagent-agent-run) | Run an agent folder on a task with Helix on your machine. |

## Factory and traces

Register what you manage, keep its agentspec in sync with the platform, record lifecycle stage runs,
and read traces by session.

| Command | What it does |
| - | - |
| [`mutagent factory list`](https://docs.mutagent.io/cli/commands/factory#mutagent-factory-list) | List the workspace's Factory entries. |
| [`mutagent factory show`](https://docs.mutagent.io/cli/commands/factory#mutagent-factory-show) | Show one entry: targets, spec version, build, components, last run per stage. |
| [`mutagent factory add`](https://docs.mutagent.io/cli/commands/factory#mutagent-factory-add) | Register an entry from its agentspec (a file, stdin or text). |
| [`mutagent factory delete`](https://docs.mutagent.io/cli/commands/factory#mutagent-factory-delete) | Archive an entry. Needs `--force`. |
| [`mutagent factory activity`](https://docs.mutagent.io/cli/commands/factory#mutagent-factory-activity) | An entry's history: spec pushes, builds, stage runs, reports. |
| [`mutagent factory builds`](https://docs.mutagent.io/cli/commands/factory#mutagent-factory-builds) | An entry's builds and the spec version each implements. |
| [`mutagent factory spec versions`, `get`, `status`, `push`](https://docs.mutagent.io/cli/commands/factory#mutagent-factory-spec) | List spec versions, print or write one, compare a local file with the platform, record a new version. |
| [`mutagent factory stage start`, `finish`, `record`, `list`, `show`](https://docs.mutagent.io/cli/commands/factory#mutagent-factory-stage) | Open and close a stage run, record a finished one, list and show runs. |
| [`mutagent traces sessions`](https://docs.mutagent.io/cli/commands/traces#mutagent-traces-sessions) | Find a session id (`hs1_…`). |
| [`mutagent traces agents`](https://docs.mutagent.io/cli/commands/traces#mutagent-traces-agents) | List the agent names seen in traces. |
| [`mutagent traces get`](https://docs.mutagent.io/cli/commands/traces#mutagent-traces-get) | One trace, or every trace of one session. |
| [`mutagent traces list`, `count`](https://docs.mutagent.io/cli/commands/traces#mutagent-traces-list) | Query traces by agent, skill, workflow, window, error, feedback or score. |
| [`mutagent traces logs`](https://docs.mutagent.io/cli/commands/traces#mutagent-traces-logs) | Read or follow a session's logs. |
| [`mutagent traces transcript`](https://docs.mutagent.io/cli/commands/traces#mutagent-traces-transcript) | Download a session's transcript as JSONL. |

## Gateway

Connect GitHub and Slack, and configure the triggers and routines that start Helix runs.

| Command | What it does |
| - | - |
| [`mutagent gateway`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway) | Show what is connected, what is missing, and the next command to run. |
| [`mutagent gateway status`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-status) | Show the workspace's connections and configuration. |
| [`mutagent gateway doctor`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-doctor) | Run an end-to-end check and report each failure with its fix. |
| [`mutagent gateway connect`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-connect) | Connect GitHub or Slack to the workspace. |
| [`mutagent gateway reconnect`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-reconnect) | Start a re-authorization attempt for a provider. |
| [`mutagent gateway disconnect`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-disconnect) | Remove a provider connection. |
| [`mutagent gateway repos`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-repos) | List the repositories the installation can reach, or the linked ones. |
| [`mutagent gateway repos link`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-repos-link) | Link repositories to the workspace. |
| [`mutagent gateway repos unlink`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-repos-unlink) | Unlink a repository and pause what depends on it. |
| [`mutagent gateway repos grant-more`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-repos-grant-more) | Print the GitHub page for granting access to more repositories. |
| [`mutagent gateway triggers`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-triggers) | List the workspace's triggers. |
| [`mutagent gateway triggers create`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-triggers-create) | Create a trigger from an event kind, a repository and an instruction. |
| [`mutagent gateway triggers show`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-triggers-show) | Show one trigger. |
| [`mutagent gateway triggers update`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-triggers-update) | Change a trigger's instruction, name, channels, stage or subject. |
| [`mutagent gateway triggers enable`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-triggers-enable) | Enable a disabled trigger. |
| [`mutagent gateway triggers disable`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-triggers-disable) | Stop a trigger firing without deleting it. |
| [`mutagent gateway triggers delete`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-triggers-delete) | Delete a trigger. |
| [`mutagent gateway triggers test`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-triggers-test) | Report whether a sample event would match, without starting a run. |
| [`mutagent gateway routines`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-routines) | List the workspace's routines with their next fire times. |
| [`mutagent gateway routines create`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-routines-create) | Create a routine from a schedule, a timezone, a repository and an instruction. |
| [`mutagent gateway routines show`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-routines-show) | Show one routine. |
| [`mutagent gateway routines update`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-routines-update) | Change a routine's schedule, instruction, name or stage. |
| [`mutagent gateway routines pause`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-routines-pause) | Stop a routine firing without deleting it. |
| [`mutagent gateway routines resume`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-routines-resume) | Start a paused routine again. |
| [`mutagent gateway routines run-now`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-routines-run-now) | Run a routine once, outside its schedule. |
| [`mutagent gateway routines delete`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-routines-delete) | Delete a routine. |
| [`mutagent gateway test-run`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-test-run) | Start a real run to prove the whole path works. |
| [`mutagent gateway runs`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-runs) | List runs from triggers, routines, test runs and `emit`. |
| [`mutagent gateway runs show`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-runs-show) | Show one run. |
| [`mutagent gateway runs logs`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-runs-logs) | Read or follow a run's logs. |
| [`mutagent gateway runs cancel`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-runs-cancel) | Cancel a run. Needs `--force`. |
| [`mutagent gateway emit`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-emit) | Send an event of your own kind. |
| [`mutagent gateway events list`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-events-list) | List the events that reached the workspace, or follow them live. |
| [`mutagent gateway notices list`](https://docs.mutagent.io/cli/commands/gateway#mutagent-gateway-notices-list) | List "could not run" notices for app mentions. |
| `mutagent gateway admin limits` | Show the workspace's run-concurrency and daily-run caps; `set` changes them (workspace admins). |

## Setup

Install Helix, and connect a project to Mutagent.

| Command | What it does |
| - | - |
| [`mutagent install helix`](https://docs.mutagent.io/cli/commands/install#mutagent-install-helix) | Install the Helix binary. |
| [`mutagent init`](https://docs.mutagent.io/cli/commands/project-setup#mutagent-init) | Write the project config file and install the Mutagent CLI skill. |
| [`mutagent skills install`](https://docs.mutagent.io/cli/commands/project-setup#mutagent-skills-install) | Install the Mutagent CLI skill for Claude Code. |
| [`mutagent hooks install`](https://docs.mutagent.io/cli/commands/project-setup#mutagent-hooks-install) | Send Claude Code session activity to Mutagent as traces. |
| [`mutagent hooks import`](https://docs.mutagent.io/cli/commands/project-setup#mutagent-hooks-import) | Send session transcripts already on disk to Mutagent as traces. |
| [`mutagent hooks claude-code`](https://docs.mutagent.io/cli/commands/project-setup#mutagent-hooks-claude-code) | The handler Claude Code runs for each hook event. |

## Reports, findings and inbox

Store Helix's run reports, follow what they found, file problems about an agent, and read your inbox.

| Command | What it does |
| - | - |
| [`mutagent reports push`](https://docs.mutagent.io/cli/commands/reports#mutagent-reports-push) | Upload a published run report. |
| [`mutagent reports update`](https://docs.mutagent.io/cli/commands/reports#mutagent-reports-update) | Change a pushed report's title, verdict or Factory links. |
| [`mutagent reports list`, `show`, `review`, `retract`](https://docs.mutagent.io/cli/commands/reports#mutagent-reports-list-show-review-retract) | List reports, show one, mark one reviewed, or delete one (`retract` needs `--force`). |
| [`mutagent findings list`, `set-status`](https://docs.mutagent.io/cli/commands/reports#mutagent-findings) | List findings from evaluator reports; resolve or reopen one. |
| [`mutagent triage file`, `list`, `show`, `set-status`](https://docs.mutagent.io/cli/commands/reports#mutagent-triage) | File a problem about an agent, skill or workflow, and follow it until it is resolved. |
| `mutagent inbox list`, `read`, `read-all` | List your inbox items, newest first; mark one or all read. See `mutagent inbox --help`. |
| `mutagent integrations sources` | Connect Langfuse or OpenObserve trace sources, test and rotate their credentials, and pull their traces: `list`, `add`, `remove`, `test`, `rotate`, `pull`, `pulls`, `pull-get`, `pull-manifest`, `pull-traces`. See `mutagent integrations sources --help`. |

## Global flags

These flags work with every command.

| Flag | What it does |
| - | - |
| `--json` | Print structured JSON instead of tables. |
| `--non-interactive` | Never prompt. `CI=true` has the same effect. |
| `--api-key <key>` | Use this Mutagent API key instead of the stored one. |
| `--endpoint <url>` | Use this Mutagent server instead of the configured one. |
| `--workspace <name-or-id>` | Run this one command in another workspace. It wins over `MUTAGENT_WORKSPACE_ID` and `mutagent workspaces use`. |
| `--org <id-or-slug>` | Check that your key belongs to this organization. On a mismatch the command exits 1 and sends nothing. |

With `mutagent helix`, put `--api-key` and `--endpoint` before `helix`:

```bash theme={null}
mutagent --api-key <mutagent-api-key> helix -p "<task>"
```

After `helix`, the CLI refuses them, so a model key cannot be sent to Mutagent as your platform key.

## Exit codes

Every command exits 0 on success, 1 on a failure (usage errors included), 2 when the key expired or
is invalid, and 3 when you are not signed in or no workspace is selected. See
[Errors and exit codes](https://docs.mutagent.io/cli/errors.md).


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