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

# CLI overview

> The Mutagent CLI signs you in, installs Helix, runs Helix and your agents in the cloud, and manages your workspace's LLM providers and Environments.

The Mutagent CLI (`mutagent`) is how you work with your Mutagent account from a terminal, a script
or a coding agent. With it you:

* sign in and choose the workspace you work in,
* install the `helix` binary on your machine,
* add the LLM provider keys your cloud runs use, and store the variables and secrets their tools need,
* run Helix and your own agents in a cloud sandbox, and deploy managed agents (your own agent,
  defined in an `agent.md` folder and hosted by Mutagent; see [Managed agents](/cli/commands/agent)).

## Get started

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    npm install -g @mutagent/cli
    ```

    Bun and pnpm work too. See [Installation](/cli/installation).
  </Step>

  <Step title="Sign in">
    ```bash theme={null}
    mutagent login
    ```

    In a terminal, the CLI asks whether to sign in with the browser or an API key. The browser
    sign-in opens app.mutagent.io, where you sign in or create an account and approve the CLI. The
    CLI waits up to 5 minutes, then saves the key on this machine.

    From a coding agent, run `mutagent login --browser --json` and show the printed URL to the person,
    or set `MUTAGENT_API_KEY` and run `mutagent login --json`. See
    [Installation](/cli/installation).
  </Step>

  <Step title="Check where you are">
    ```bash theme={null}
    mutagent workspaces current
    ```

    ```text theme={null}
    ℹ Key scope: organization
    ℹ Organization: acme (org_…)
    ℹ Workspace: Default Workspace (<workspace-id>)
    ℹ Key expires: 2026-10-13T15:51:27.381Z
    ```

    Every command works in this workspace. To choose another one, run
    `mutagent workspaces use <name>`. See [Workspaces](/cli/commands/login#mutagent-workspaces-use).
    A coding agent runs `mutagent workspaces current --json`: exit code 0 and a `workspace` object
    mean it is ready.
  </Step>

  <Step title="Install Helix">
    ```bash theme={null}
    mutagent install helix
    ```

    Then run `helix` in your project and follow [your first loop](/helix/install/first-loop).
  </Step>
</Steps>

## Commands by what they are for

| You want to | Commands | Page |
| - | - | - |
| Sign in, pick a workspace | `login`, `auth`, `workspaces`, `config` | [Sign-in and workspaces](/cli/commands/login) |
| Add the model keys cloud runs use | `providers` | [LLM providers](/cli/commands/providers) |
| Store variables and secrets for tools | `env` | [Environments](/cli/commands/env) |
| Run Helix in a cloud sandbox | `helix`, `helix agent`, `helix session`, `helix models` | [mutagent helix](/cli/commands/helix) |
| Deploy and run your own agent | `agent` | [Managed agents](/cli/commands/agent) |
| Start runs from GitHub, Slack, webhooks or a schedule | `gateway` | [mutagent gateway](/cli/commands/gateway) |
| See which sandbox providers and presets (named sandbox definitions) a run can use | `sandbox providers`, `sandbox presets` | [mutagent sandbox](/cli/commands/sandbox) |
| Install Helix on this machine | `install helix` | [mutagent install](/cli/commands/install) |
| Connect a project | `init`, `skills`, `hooks` | [Project setup](/cli/commands/project-setup) |
| Store Helix's evaluation and diagnosis reports, track the problems they found (findings) and the ones you filed for follow-up (triage) | `reports`, `findings`, `triage` | [Reports, findings and triage](/cli/commands/reports) |
| Read your inbox, connect trace sources | `inbox`, `integrations` | `mutagent inbox --help`, `mutagent integrations --help` |
| See your account, send feedback | `usage`, `feedback` | [Account](/cli/commands/account) |

To run Helix in the cloud, deploy managed agents or connect GitHub and Slack, see
[Helix Cloud](/helix/cloud/overview).

The [command reference](/cli/commands) lists every command. `mutagent <command> --help` prints the
same information in your terminal.

## Flags that work with every command

Put these before the command name, as in `mutagent --workspace prod env list`:

| Flag | What it does |
| - | - |
| `--json` | Print one JSON object instead of text. See [Scripts, CI and coding agents](/cli/json). |
| `--workspace <name-or-id>` | Run this one command in another workspace. |
| `--org <id-or-slug>` | Check that your key belongs to this organization. If it does not, the command stops with exit code 1 and sends nothing. |
| `--api-key <key>` | Use this API key instead of the saved one. |
| `--endpoint <url>` | Send requests to another API address. The default is `https://api.mutagent.io`. |
| `--non-interactive` | Never ask a question. `CI=true`, or a stdin that is not a terminal, does the same. |

With `mutagent helix`, `--api-key` and `--endpoint` must come before `helix`. After it they are
refused, so a model key can never be sent to Mutagent by mistake.

`mutagent --version` (or `-v`) prints the CLI version. `mutagent helix --version` (needs a sign-in)
reports the Helix version that cloud sandboxes run. For the Helix installed on this machine, run
`helix --version`.

## When a command fails

The CLI prints what went wrong and the command that fixes it, and exits with a code that says what
kind of failure it was: 1 for a failure, 2 for an expired or invalid key, 3 when you are not signed
in or no workspace is selected. Commands that delete something never ask for confirmation: they need
`--force`. See [Errors and exit codes](/cli/errors).


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