CLI overview - MUTAGENT

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

Get started

Install the CLI

npm install -g @mutagent/cli

Bun and pnpm work too. See Installation.

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.

Check where you are

mutagent workspaces current

ℹ 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. A coding agent runs mutagent workspaces current --json: exit code 0 and a workspace object mean it is ready.

Install Helix

mutagent install helix

Then run helix in your project and follow your first loop.

Commands by what they are for

You want to	Commands	Page
Sign in, pick a workspace	`login`, `auth`, `workspaces`, `config`	Sign-in and workspaces
Add the model keys cloud runs use	`providers`	LLM providers
Store variables and secrets for tools	`env`	Environments
Run Helix in a cloud sandbox	`helix`, `helix agent`, `helix session`, `helix models`	mutagent helix
Deploy and run your own agent	`agent`	Managed agents
Start runs from GitHub, Slack, webhooks or a schedule	`gateway`	mutagent gateway
See which sandbox providers and presets (named sandbox definitions) a run can use	`sandbox providers`, `sandbox presets`	mutagent sandbox
Install Helix on this machine	`install helix`	mutagent install
Connect a project	`init`, `skills`, `hooks`	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
Read your inbox, connect trace sources	`inbox`, `integrations`	`mutagent inbox --help`, `mutagent integrations --help`
See your account, send feedback	`usage`, `feedback`	Account

To run Helix in the cloud, deploy managed agents or connect GitHub and Slack, see Helix Cloud. The command reference 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.
`--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.

​Get started

​Commands by what they are for

​Flags that work with every command

​When a command fails

Get started

Commands by what they are for

Flags that work with every command

When a command fails