@mutagent/cli

v0.2.9

Published

4 hours ago

Bun-native CLI for the MutagenT AI platform - auth, provider config, and lifecycle-tool installer for AI-native workflows

0High
0Medium
0Low

bcmutagent

ai agent cli mutagent byok providers diagnostics evaluator claude-code

MutagenT CLI

MutagenT CLI is the command-line client for the MutagenT AI platform. It handles authentication, BYOK LLM providers, workspace Environments, managed agents, cloud sandboxes and Helix sessions, and the standalone Helix binary installer.

Status: all commands and flags below were verified against mutagent --help (and each subcommand's --help) on this branch. sandbox is internal (everyday use goes through mutagent helix); trace is not implemented in this binary — it prints where to find it (in Helix) and exits with an error.

Context · Concepts · Components · Configuration · Reference

Context

MutagenT CLI is the entry point AI coding agents and developers use to sign in, configure a project, manage BYOK LLM provider keys, check usage, manage workspace Environments (secrets for agent tools), package and deploy managed agents, and install or run Helix. It is a thin, --json-first client over the MutagenT API (the backend server); the generated @mutagent/sdk is what most commands call underneath. For where the CLI sits relative to the rest of the platform, see the root README's architecture section.

Key features

AI-first: every platform command supports --json with _directive and _links; a mutagent helix run streams Helix's own output unchanged
One-command auth: mutagent login handles signup, onboarding and CLI authorization via browser OAuth (or an API key for CI)
LLM providers (BYOK): configure and test your own provider keys (mutagent providers), or copy them from a local Helix login (mutagent providers mirror)
Workspace Environments: mutagent env holds the variables and secrets an agent's tools need, separate from LLM provider keys
Managed agents: mutagent agent checks, packages, deploys and runs agent.md folders; mutagent helix agent @slug runs a deployed one in the cloud
Helix installer: mutagent install helix installs the standalone Helix binary into ~/.mutagent/bin (no login needed)
Claude Code integration: install the CLI skill (mutagent skills install) and session-telemetry hooks (mutagent hooks install)
Built-in feedback: mutagent feedback send reports bugs and product feedback, optionally with your coding-agent session transcript

Concepts

Workspace — the tenant scope most commands operate in (mutagent config set workspace <id>, mutagent workspaces). An org-scoped API key must also set an org (mutagent config set org <id>).
LLM provider (BYOK) — a key for a model provider (OpenAI, Anthropic, Google, …) registered to the workspace so Helix can call it in the cloud (mutagent providers). Not the same as a workspace Environment variable.
Workspace Environment — a named bundle of variables and secrets an agent's tools need (a GitHub token, a database URL), loaded into a cloud run with mutagent helix --env <name> (mutagent env). Values are write-only: env show prints fingerprints, never values.
Managed agent — a folder whose entry file is agent.md (YAML frontmatter + prompt). mutagent agent checks, packages and deploys it; each deploy is a new revision, and a slot is the agent in one Environment (--env, default slot when omitted).
Helix session — a running or checkpointed cloud Helix run, addressed by a reference (hs1_…). mutagent helix starts one; mutagent helix session lists, attaches to, signals, checkpoints and restores one.
Sandbox — the cloud VM a Helix session or agent run executes in. Idle 15 minutes → stopped (interactive sessions checkpoint first). mutagent sandbox manages sandboxes directly; everyday use goes through mutagent helix, which spawns one implicitly.
JSON directive protocol — --json responses may carry _directive (a rendered status card and next-step instructions for a coding agent) and _links (dashboard/API URLs). See JSON Directive & Links.

%%{init: {"theme":"base","themeVariables":{"background":"#0d1117","primaryColor":"#161b22","primaryTextColor":"#e6edf3","primaryBorderColor":"#30363d","lineColor":"#8b949e","clusterBkg":"#0d1117","clusterBorder":"#444c56","secondaryColor":"#1a3a5c","tertiaryColor":"#2a1a4a","edgeLabelBackground":"#161b22","tertiaryTextColor":"#e6edf3","titleColor":"#e6edf3","fontFamily":"ui-sans-serif, system-ui, sans-serif","fontSize":"15px"},"flowchart":{"nodeSpacing":28,"rankSpacing":42,"curve":"basis"}}}%%
flowchart TD
    INSTALL["npm i -g @mutagent/cli"] --> AUTH_CHOICE{How to authenticate?}

    AUTH_CHOICE -->|Interactive / browser OAuth| LOGIN["mutagent login"]
    AUTH_CHOICE -->|Force browser| LOGIN_B["mutagent login --browser"]
    AUTH_CHOICE -->|CI / env var| ENV_AUTH["export MUTAGENT_API_KEY=mg_live_...<br/>mutagent login --json"]

    LOGIN --> INIT["mutagent init<br/>(.mutagentrc.json)"]
    LOGIN_B --> INIT
    ENV_AUTH --> INIT

    INIT --> SETUP

    subgraph SETUP ["Project Setup & Discovery"]
        direction TB

        subgraph AUTH_CMDS ["Auth & Config"]
            AUTH_STATUS["mutagent auth status"]
            AUTH_LOGOUT["mutagent auth logout"]
            CONFIG_LIST["mutagent config list"]
            CONFIG_SET_WS["mutagent config set workspace <id>"]
            CONFIG_SET_ORG["mutagent config set org <id>"]
        end

        subgraph PLATFORM_CMDS ["Platform (read-only)"]
            WS_LIST["mutagent workspaces list"]
            WS_GET["mutagent workspaces get <id>"]
            USAGE["mutagent usage"]
        end

        subgraph PROVIDER_CMDS ["LLM providers (BYOK)"]
            PROV_LIST["mutagent providers list"]
            PROV_ADD["mutagent providers add"]
            PROV_MIRROR["mutagent providers mirror"]
        end

        subgraph AGENT_TOOLING ["Coding-Agent Tooling"]
            SKILLS["mutagent skills install"]
            HOOKS["mutagent hooks install"]
        end

        subgraph CLOUD ["Cloud execution"]
            SANDBOX["mutagent sandbox"]
            ENVIRONMENT["mutagent env"]
            HELIX["mutagent helix"]
            AGENT["mutagent agent"]
            TRACE["mutagent trace<br/>(→ Helix)"]
        end

        subgraph LIFECYCLE ["Helix & Feedback"]
            INSTALL_PKG["mutagent install helix"]
            FEEDBACK["mutagent feedback send"]
        end
    end

    AUTH_CMDS ~~~ PLATFORM_CMDS ~~~ PROVIDER_CMDS
    AGENT_TOOLING ~~~ CLOUD ~~~ LIFECYCLE

    classDef default fill:#161b22,stroke:#444c56,color:#e6edf3
    classDef surface fill:#1a3a5c,stroke:#4a90e2,color:#fff
    classDef runtime fill:#2d4a2d,stroke:#4a9e4a,color:#fff
    classDef tool fill:#2a1a4a,stroke:#bc8cff,color:#fff
    classDef data fill:#4a3a2d,stroke:#cc9944,color:#fff
    classDef external fill:#3a3a4a,stroke:#888,color:#e6edf3
    class INSTALL,LOGIN,LOGIN_B,ENV_AUTH,INIT surface
    class AUTH_CHOICE,AUTH_STATUS,AUTH_LOGOUT,CONFIG_LIST,CONFIG_SET_WS,CONFIG_SET_ORG,SKILLS,HOOKS tool
    class SANDBOX,ENVIRONMENT,HELIX,AGENT,TRACE,PROV_LIST,PROV_ADD,PROV_MIRROR runtime
    class WS_LIST,WS_GET,USAGE,INSTALL_PKG,FEEDBACK data

Components

mutagent-cli/
├── src/
│   ├── bin/cli.ts        # Commander entry point; registers every top-level command
│   ├── commands/         # One module per command (auth, config, workspaces, usage,
│   │                     #   init, skills, hooks/, install/, providers/, env/,
│   │                     #   agent/, helix/, sandbox/, feedback)
│   ├── lib/               # Config resolution, auth flow, SDK client, brand/TTY,
│   │                     #   agent packaging, installer, session API
│   ├── generated/        # Skill content baked from .claude/skills/mutagent-cli (sync-skill)
│   └── types/            # Shared types
├── src/__tests__/        # Unit tests (5+ per subcommand: structure, happy, error, json, edge)
├── tests/                # Integration + pipe tests, fixtures (agent-deployment example)
├── docs/helix-surface-map.md  # Earlier verb → API map; superseded by Command surface below
└── scripts/              # sync-skill.ts, build.ts, workspace-resolution check

Entry point: src/bin/cli.ts, built to dist/bin/cli.js (the mutagent bin).

Commands (package scripts)

| Command | What it does | |---|---| | bun run dev | Runs the CLI from source (sync-skill then src/bin/cli.ts) | | bun run build | Builds dist/ | | bun run build:binary | Builds the standalone binary for the host platform; build:binary:<os>-<arch> targets one explicitly | | bun run type-check | tsc --noEmit for src/ and the test tsconfig | | bun run lint / lint:fix | ESLint over src (excluding __tests__) and src/__tests__ | | bun run test | bun test src/ — the verification gate for this package | | bun run test:integration | bun test tests/pipe/ (30s timeout) | | bun run verify | workspace-resolution check + lint + type-check + build |

Run bun run with no arguments in mutagent-cli/ to list every script. Never run bun test at the monorepo root — this package's suite must run scoped (cd mutagent-cli && bun run test).

Prerequisites

Bun >= 1.1.0
Node.js >= 22.18 (fallback runtime; Bun is primary)

Setup

git clone https://github.com/architech-printworks/mutagent-monorepo.git
cd mutagent-monorepo
bun install
cd mutagent-cli

Reference material

Command Reference below — every command, verified against --help
Command surface — the helix and agent trees mapped to API routes and CLI source
tests/fixtures/agent-deployment — a complete agent.md example

Configuration

Environment variables

Read at cites this branch's mutagent-cli/src. Secret marks values that must never be logged or committed. None of these are required to run mutagent --help; MUTAGENT_API_KEY is required for non-interactive/CI login.

| Variable | Required | Default | Read at | Secret | Purpose | |---|---|---|---|---|---| | MUTAGENT_API_KEY | For non-interactive/CI login | none | src/lib/config.ts:83, src/lib/auth-flow.ts:49, src/bin/cli.ts:214-215 | Yes | Platform API key; skips interactive login | | MUTAGENT_ENDPOINT | No | https://api.mutagent.io | src/lib/config.ts:84, src/lib/auth-flow.ts:50, src/bin/cli.ts:217-218 | No | Overrides the API endpoint | | MUTAGENT_APP_URL | No | https://app.mutagent.io | src/lib/ui-links.ts:17 | No | Dashboard base URL used in printed links | | MUTAGENT_WORKSPACE_ID | No | from .mutagentrc.json / stored credentials | src/lib/config.ts:92,106, src/commands/providers/mirror.ts:168 | No | Default workspace id | | MUTAGENT_NON_INTERACTIVE | No | unset | src/bin/cli.ts:221, src/lib/auth-flow.ts:60, src/lib/tty.ts:20, src/commands/providers/mirror.ts:222 | No | true disables all interactive prompts | | CI | No | unset | src/bin/cli.ts:220, src/lib/auth-flow.ts:61, src/lib/tty.ts:21 | No | true also enables non-interactive mode | | NO_COLOR | No | unset | src/lib/tty.ts:19 | No | Any non-empty value disables color and interactive-TTY behavior | | MUTAGENT_NO_BANNER | No | unset | src/lib/brand.ts:105 | No | 1 disables the CLI's banner | | COLORTERM | No (set by the terminal) | unset | src/lib/brand.ts:82 | No | truecolor/24bit enables the gradient banner | | MUTAGENT_DEBUG | No | unset | src/lib/sdk-debug.ts:36 | No | Truthy value enables the generated SDK's debug logging | | MUTAGENT_SANDBOX_TOKEN_FILE | No | internal cache path | src/lib/sandbox-token.ts:79 | No | Overrides where the cached sandbox operator token is stored | | MUTAGENT_SUBAGENTS_BUNDLE_DIR | No | none | src/commands/helix/agent-argv.ts:457 | No | Extra root directory searched for subagent bundles | | HELIX_CODING_AGENT_DIR | No | ~/.mutagent/agent | src/commands/helix/agent-argv.ts:458, src/lib/helix-local-store.ts:51 | No | Local Helix agent directory; also read for providers mirror | | PI_CODING_AGENT_DIR | No | ~/.omp/agent | src/lib/transcript.ts:120 | No | Local OMP/Pi agent directory used for transcript lookups | | MUTAGENT_HELIX_CHANNEL | No | latest | src/lib/installer-helix.ts:294 | No | Release channel for mutagent install helix when --channel is not passed | | MUTAGENT_INSTALL_HOST | No | https://install.mutagent.io | src/lib/installer-helix.ts:296-297 | No | Install host for mutagent install helix (must be https://, except loopback) | | MUTAGENT_INSTALL_DIR | No | ~/.mutagent/bin | src/lib/installer-helix.ts:301-302 | No | Install directory for mutagent install helix | | PATH | No (platform) | inherited from the shell | src/lib/installer-helix.ts:347 | No | Checked to report whether the install directory is already on PATH | | CLI_VERSION | No (build-set) | the package.json version | src/bin/cli.ts:63-64, src/commands/feedback.ts:78, src/lib/install-telemetry.ts:80 | No | Overrides the reported CLI version (set when building the standalone binary) | | MUTAGENT_TEST_MODE | No (test harness only) | unset | src/lib/browser-auth.ts:140 | No | true bypasses the real browser OAuth flow in integration tests — not for product use | | MUTAGENT_TEST_API_URL | No (test harness only) | http://localhost:3003 | src/__tests__/helpers/sdk-client-factory.ts:55 | No | Test-only SDK client base URL — not for product use | | MUTAGENT_TEST_API_KEY | No (test harness only) | test-key | src/__tests__/helpers/sdk-client-factory.ts:56 | No | Test-only SDK client API key — not for product use | | MUTAGENT_TEST_WORKSPACE_ID | No (test harness only) | none | src/__tests__/helpers/sdk-client-factory.ts:58 | No | Test-only default workspace id for the test SDK client — not for product use | | MUTAGENT_TEST_ORG_ID | No (test harness only) | none | src/__tests__/helpers/sdk-client-factory.ts:66 | No | Test-only default org id for the test SDK client — not for product use | | MUTAGENT_TEST_REAL_SDK | No (test harness only) | unset | src/__tests__/helpers/sdk-client-factory.ts:32 | No | true runs integration tests against a real SDK client instead of a mock — not for product use | | OPENAI_API_KEY | No (test harness only) | none | src/__tests__/commands/providers-mirror.test.ts:425,427 | Yes | Saved/restored around a providers mirror test fixture — not read by product code | | OPENROUTER_API_KEY | No (test harness only) | none | src/__tests__/commands/providers-mirror.test.ts:425 | Yes | Saved/restored around a providers mirror test fixture — not read by product code |

MUTAGENT_HELIX_BIN and MUTAGENT_BUN_BIN are documented by mutagent agent --help (select a local Helix binary and Bun binary for agent run/compilation) but are resolved inside the @mutagent/agents package, not this package's src/ — they are not in the table above for that reason.

An example file with placeholder values is at .env.example; the CLI does not auto-load a .env file itself, but Bun does when you run it with bun run dev from this directory.

RC file

mutagent init writes .mutagentrc.json (skipped if one already exists):

{
  "endpoint": "https://api.mutagent.io",
  "format": "table"
}

mutagent config set workspace <id> / mutagent config set org <id> add defaultWorkspace / defaultOrganization to the same file.

Global config

Credentials are stored in ~/.config/mutagent/credentials.json, created by mutagent login. No ports: this package is a CLI, not a server.

Reference

Installation

# Bun (recommended)
bun install -g @mutagent/cli

# npm
npm install -g @mutagent/cli

Standalone binary: build one from this monorepo with bun run build:binary in mutagent-cli/ (per-target scripts also exist for Linux, macOS and Windows).

mutagent --version   # Verify installation

Quick start

# 1. Authenticate
mutagent login                        # Browser OAuth (recommended)
mutagent login --browser              # Force browser flow
export MUTAGENT_API_KEY="mg_live_xxxx" && mutagent login --json   # CI / AI agent
mutagent auth login                   # Back-compat alias for `mutagent login`

# 2. Initialize your project
mutagent init                         # Writes .mutagentrc.json + installs the CLI skill
mutagent auth status                  # Confirm state

# 3. Configure LLM providers (BYOK)
mutagent providers mirror             # Copy keys from a local Helix login, or:
mutagent providers add                # Add one manually
mutagent providers test <provider-id> # Verify connectivity

# 4. Install Helix
mutagent install helix                       # → ~/.mutagent/bin/helix
mutagent install helix --channel candidate   # Candidate build

# 5. Wire up your coding agent
mutagent skills install               # Installs .claude/skills/mutagent-cli/SKILL.md
mutagent hooks install                # Installs session-telemetry hooks

mutagent login is the canonical command; mutagent auth login is a back-compat alias, both identical.

Command reference

The active command surface: login · auth · config · workspaces · providers · usage · init · skills · hooks · install · sandbox · env · helix · agent · trace · feedback.

Run mutagent <command> --help for the authoritative, current flag list — the CLI is the source of truth for flags.

Global options

| Option | Description | |---|---| | --json | Output results as JSON (for AI agents) | | --api-key <key> | Mutagent platform API key for this command | | --endpoint <url> | Mutagent server endpoint for this command | | --non-interactive | Disable interactive prompts (for CI/AI agents) | | -h, --help | Display help for command | | -v, --version | CLI version (only before a subcommand) |

Authentication (`login` / `auth`)

mutagent login                      # Browser OAuth (recommended)
mutagent login --browser            # Force browser flow
mutagent login --json               # Non-interactive (uses MUTAGENT_API_KEY)

mutagent auth login                 # Back-compat alias for `mutagent login`
mutagent auth status                # Sign-in state, endpoint and active workspace
mutagent auth logout                # Clear stored credentials

Configuration (`config`)

mutagent config list                # List all config values
mutagent config get <key>           # apiKey, endpoint, format, timeout, defaultWorkspace, defaultOrganization
mutagent config set workspace <id>  # Set default workspace
mutagent config set org <id>        # Set default organization

Project setup (`init`)

mutagent init   # Writes .mutagentrc.json + installs the CLI skill. Never prompts.

Workspaces (`workspaces`, read-only)

mutagent workspaces list            # List all workspaces
mutagent workspaces list --limit 20 --offset 0
mutagent workspaces get <id>        # Workspace details

Create or change workspaces in the dashboard (https://app.mutagent.io).

LLM providers (`providers`)

mutagent providers mirror           # Copy API keys from your local Helix login store
mutagent providers list             # List configured LLM providers
mutagent providers list --models    # Show available models per LLM provider
mutagent providers get <id>         # LLM provider details
mutagent providers test <id>        # Test LLM provider connectivity

# Manage keys
mutagent providers add              # Add an LLM provider (--provider, --name, --api-key-stdin or --api-key, --base-url, --set-default)
mutagent providers update <id> --name "New name" --active true
mutagent providers delete <id> --force

LLM provider types: openai, anthropic, google, moonshot, glm, deepseek, xai, azure, vertex, bedrock, custom.

Workspace Environments (`env`)

mutagent env list                                            # List the workspace's Environments
mutagent env set demo GREETING=hello --secret GITHUB_TOKEN=ghp_…
mutagent env set staging --from-file .env.staging --secrets-from-file .env.staging.secrets
mutagent env show demo                                       # Entry names + fingerprints — never a value
mutagent env unset demo GREETING
mutagent env delete demo --force
mutagent helix --env demo -p "check the deploy"              # Load it into a Helix cloud run

An Environment holds the variables and secrets an agent's tools need, distinct from LLM provider keys (mutagent providers) — a variable named like a provider key (ANTHROPIC_API_KEY, …) is refused unless --allow-provider-key. set merges into an existing Environment (PATCH); --replace overwrites it (PUT) and removes entries you don't name. Names: Environments use letters, digits, ., _ and - (up to 64 chars); variables use A-Z, 0-9 and _, not starting with a digit. An Environment holds up to 64 KiB. Requires a workspace (mutagent config set workspace <id>).

Usage (`usage`)

mutagent usage         # Account usage + LLM provider status
mutagent usage --json  # Machine-readable

Skills & hooks (Claude Code)

mutagent skills install               # Creates .claude/skills/mutagent-cli/SKILL.md
mutagent hooks install                # Merges hooks into .claude/settings.local.json (11 events)
mutagent hooks install --cwd ./path   # Target a specific directory
mutagent hooks import <files...>      # Upload Helix session transcripts as traces

Managed agents (`agent`, `helix agent @slug`)

A managed agent is a folder whose entry file is agent.md: YAML frontmatter, then the standing prompt. The base fields (name, description, model, thinking, tools, disallowed_tools, skills) are a local brief; one optional harness: block holds the deployment settings (tools, skills, files, bindings, runtime). A complete example is in tests/fixtures/agent-deployment.

mutagent agent check ./invoice/agent.md
mutagent agent pack ./invoice/agent.md --output ./invoice.tgz
mutagent agent run ./invoice/agent.md "Price three widget units."
mutagent agent deploy ./invoice/agent.md --env prod
mutagent helix agent @invoice-pricing --env prod -p "Price three widget units."
mutagent agent inspect invoice-pricing --env prod
mutagent agent activate invoice-pricing --revision v2 --env prod
mutagent agent retire invoice-pricing --env prod
mutagent agent list

name is the slug. model is provider/model, as mutagent helix models lists it; deploy and activate refuse a model outside the workspace model list.
Each deploy of new content is the next revision (v1, v2, ...); unchanged content reuses its revision. A slot is the agent in one Environment: --env names it, and no --env is the default slot. --no-activate stores the revision without moving the slot.
mutagent helix agent @slug[:vN|:latest] [--env X] (-p "<task>" | --rpc) runs it in the cloud. The receipt is one JSON line on stderr; its reference is what mutagent helix session commands take.
agent run runs a local agent.md on this machine with the local Helix binary (mutagent install helix puts one at ~/.mutagent/bin/helix; MUTAGENT_HELIX_BIN selects another) and creates nothing in the workspace.
Compilation requires Bun 1.3.14 on PATH or MUTAGENT_BUN_BIN.

Helix installer (`install`)

mutagent install helix                       # latest channel
mutagent install helix --channel candidate   # candidate channel
mutagent install helix --json                # binaryPath, version, sha256, onPath, pathLine

mutagent install helix does what curl -fsSL https://install.mutagent.io/helix | bash does: it downloads helix-<os>-<arch> (macOS or Linux, x64 or arm64) from https://install.mutagent.io/<channel>/, verifies it against checksums.txt from the same origin, writes ~/.mutagent/bin/helix with the mutagent-helix alias, and runs helix --version. No login is needed. Shell rc files are never changed: when the directory is not on PATH, the line to add is printed. (The PATH step is where the two differ: the curl installer also symlinks helix into ~/.local/bin or ~/bin when one of them is already on PATH; this command does not.) When you are signed in, the CLI also records the install activation, best-effort; --json reports it as telemetry (sent, skipped or failed).

diagnostics and evaluator are not install targets: both skills ship inside helix — passing either name fails with INVALID_ARGUMENTS naming helix instead.

See the Configuration table above for MUTAGENT_HELIX_CHANNEL, MUTAGENT_INSTALL_HOST and MUTAGENT_INSTALL_DIR.

Sandbox management (`sandbox`, internal)

Everyday use goes through mutagent helix, which spawns a sandbox implicitly. mutagent sandbox manages one directly — useful for scripted or long-lived work:

mutagent sandbox presets                          # Presets `mutagent helix --preset` can name
mutagent sandbox providers                        # Providers `mutagent helix --sandbox-provider` can name
mutagent sandbox preflight --image alpine:3.20    # Would this definition run?
mutagent sandbox spawn --image alpine:3.20 --detach
mutagent sandbox list
mutagent sandbox status sbx_1
mutagent sandbox exec --sandbox sbx_1 -- bun test
mutagent sandbox attach sbx_1 --since 412
mutagent sandbox traces sbx_1                     # Spans recorded for a sandbox
mutagent sandbox delete sbx_1 --force

exec without --sandbox runs one command in a fresh, one-shot sandbox and removes it; spawn leaves a sandbox running for attach/exec --sandbox. A sandbox idle 15 minutes is stopped (an interactive Helix session in it is checkpointed first); mutagent helix session restore <reference> rebuilds it. Requires a workspace (mutagent config set workspace <id>).

Feedback (`feedback`)

mutagent feedback send "describe what went wrong" --category cli
mutagent feedback send "eval gate unclear" --category stage:evaluate
mutagent feedback send "the CLI crashed on init" \
  --category cli --session <session-id> --attach-transcript

| Flag | Description | |---|---| | <feedback> | Feedback body / content (required, ≤10000 chars) | | --title <string> | Optional 5–8 word summary of the session timeline | | --category <value> | cli (default) · helix · stage:<spec\|build\|evaluate\|diagnose\|optimize> | | --session <id> | Link feedback to a session id (server sessionId) | | --attach-transcript [path] | Attach the coding-agent session JSONL (bare = auto-detect newest) |

--attach-transcript uploads the full session JSONL (source code, absolute paths, repo names, internal hostnames) — use it only when explicitly asked to.

Command surface

The mutagent helix and mutagent agent trees and their API routes. The command definitions in src/commands are the source of truth.

%%{init: {"theme":"base","themeVariables":{"background":"#0d1117","primaryColor":"#161b22","primaryTextColor":"#e6edf3","primaryBorderColor":"#30363d","lineColor":"#8b949e","clusterBkg":"#0d1117","clusterBorder":"#444c56","secondaryColor":"#1a3a5c","tertiaryColor":"#2a1a4a","edgeLabelBackground":"#161b22","tertiaryTextColor":"#e6edf3","titleColor":"#e6edf3","fontFamily":"ui-sans-serif, system-ui, sans-serif","fontSize":"15px"},"flowchart":{"nodeSpacing":28,"rankSpacing":42,"curve":"basis"}}}%%
flowchart LR
  ROOT["mutagent"] --> HX["helix"]
  ROOT --> AG["agent"]

  HX --> HXRUN["helix -p or --mode json or --mode rpc<br/>classic arm, --prime selects the prime arm"]
  HX --> HXAGENT["helix agent"]
  HX --> HXSESSION["helix session"]
  HX --> HXMODELS["helix models"]
  HX --> HXDOCTOR["helix doctor"]
  HX --> HXSMOKE["helix smoke"]
  HX --> HXVERSION["helix version"]
  HX --> HXUPDATE["helix update<br/>always refused"]

  HXAGENT --> HXAGENTDEF["definition: positional, --prompt, --file, --name"]
  HXAGENT --> HXAGENTSLUG["@slug, @slug:vN, @slug:latest<br/>managed agent"]

  HXSESSION --> SLS["list"]
  HXSESSION --> SATTACH["attach"]
  HXSESSION --> SSEND["send"]
  HXSESSION --> SSIGNAL["signal"]
  HXSESSION --> SCLOSE["close-input"]
  HXSESSION --> SCHECKPOINT["checkpoint"]
  HXSESSION --> SCHECKPOINTS["checkpoints"]
  HXSESSION --> SRESTORE["restore"]
  HXSESSION --> SSTART["start<br/>internal, sandbox id"]

  HXMODELS --> MDEFAULT["default"]

  AG --> ACHECK["check<br/>local"]
  AG --> APACK["pack<br/>local"]
  AG --> ARUN["run<br/>local Helix binary"]
  AG --> ADEPLOY["deploy"]
  AG --> AACTIVATE["activate"]
  AG --> ALIST["list"]
  AG --> AINSPECT["inspect"]
  AG --> ARETIRE["retire"]

    classDef default fill:#161b22,stroke:#444c56,color:#e6edf3
    classDef surface fill:#1a3a5c,stroke:#4a90e2,color:#fff
    classDef runtime fill:#2d4a2d,stroke:#4a9e4a,color:#fff
    classDef tool fill:#2a1a4a,stroke:#bc8cff,color:#fff
    classDef data fill:#4a3a2d,stroke:#cc9944,color:#fff
    classDef external fill:#3a3a4a,stroke:#888,color:#e6edf3
    class ROOT,HX,AG surface
    class HXRUN,HXAGENT,HXSESSION,HXAGENTDEF,HXAGENTSLUG,ARUN,ADEPLOY,AACTIVATE runtime
    class HXMODELS,HXDOCTOR,HXSMOKE,HXVERSION,MDEFAULT,ACHECK,APACK tool
    class SLS,SATTACH,SSEND,SSIGNAL,SCLOSE,SCHECKPOINT,SCHECKPOINTS,SRESTORE,SSTART,ALIST,AINSPECT,ARETIRE data
    class HXUPDATE external

Registration: mutagent-cli/src/bin/cli.ts registers helix and agent; mutagent-cli/src/commands/helix/index.ts attaches agent, session, models, doctor, smoke, version and update; mutagent-cli/src/commands/helix/session-commands.ts attaches the session verbs; mutagent-cli/src/commands/agent/index.ts declares the agent verbs.

Credentials

The two trees authenticate differently.

mutagent helix … goes through requestJson (mutagent-cli/src/lib/sandbox-api.ts). Each request carries Authorization: Bearer <operator token> and x-workspace-id. The operator token is minted from the platform API key by POST /api/sandbox/token (mutagent-cli/src/lib/sandbox-token.ts) and cached; a 401 drops the cached token and mints once more.
mutagent agent … (the remote verbs) goes through the generated SDK client sdk.managedAgents with the platform API key and an x-workspace-id header, and no token exchange (mutagent-cli/src/lib/agent/sdk.ts). The server mounts these routes under /api/helix-agent (mutagent/src/modules/helix-agent/deployment/module.ts).

`mutagent helix` verbs

<ref> is a session reference (hs1_…). SESSIONS is /api/sandbox/helix/sessions (mutagent-cli/src/lib/helix-session-api.ts).

| Verb | API call | CLI source | |---|---|---| | helix [argv…] (classic arm; --prime = prime arm) | POST SESSIONS (launch), then the attach loop below | commands/helix/index.ts → commands/helix/run-cloud.ts → lib/helix-session-api.ts | | helix … --sandbox <id> (internal) | POST /api/sandbox/:id/session, then the attach loop | commands/helix/run-cloud.ts → lib/sandbox-api.ts | | attach loop after a launch | GET SESSIONS/<ref>/stream[?since=]; stdin lines POST SESSIONS/<ref>/input; stdin EOF POST SESSIONS/<ref>/close-input; Ctrl-C POST SESSIONS/<ref>/signal {signal: SIGINT} | commands/helix/run-cloud.ts; lib/helix-session-api.ts | | helix --version, -v | GET /api/sandbox/presets (the preset description, not a live probe) | commands/helix/index.ts → commands/helix/doctor.ts → lib/sandbox-catalog.ts | | helix agent <definition> … | POST SESSIONS with arm: agent (or POST /api/sandbox/:id/session with --sandbox), then the attach loop | commands/helix/agent.ts → commands/helix/run-cloud.ts | | helix agent @slug[:vN\|:latest] | POST SESSIONS with body agent: {slug, revision?}, mode when -p or --rpc is given, args: ["-p", task]; prints the receipt {reference, sandboxId, agent, mode} on stderr; then the attach loop | commands/helix/agent.ts → commands/helix/managed-agent.ts → commands/helix/run-cloud.ts | | helix session list | GET SESSIONS[?limit=&cursor=] | commands/helix/session-commands.ts → lib/helix-session-api.ts | | helix session list <sandbox-id> (internal) | GET /api/sandbox/:id/sessions | commands/helix/session-commands.ts → lib/sandbox-api.ts | | helix session attach <ref> | GET SESSIONS/<ref>/stream[?since=] | commands/helix/session-commands.ts → lib/helix-session-api.ts | | helix session send <ref> | POST SESSIONS/<ref>/input {line} | commands/helix/send.ts → lib/helix-session-api.ts | | helix session send <id> --session <sid> (internal) | POST /api/sandbox/:id/input {sessionId, line} | commands/helix/send.ts → lib/sandbox-api.ts | | helix session signal <ref> | POST SESSIONS/<ref>/signal {signal} (default SIGINT) | commands/helix/signal.ts → lib/helix-session-api.ts | | helix session signal <id> --session <sid> (internal) | POST /api/sandbox/:id/signal {sessionId, signal} | commands/helix/signal.ts → lib/sandbox-api.ts | | helix session close-input <ref> | POST SESSIONS/<ref>/close-input | commands/helix/reference-commands.ts → lib/helix-session-api.ts | | helix session checkpoint <ref> | POST SESSIONS/<ref>/checkpoint | commands/helix/session-commands.ts → lib/helix-session-api.ts | | helix session checkpoint <id> --session <sid> (internal) | POST /api/sandbox/:id/checkpoint | commands/helix/session-commands.ts → lib/sandbox-checkpoints.ts | | helix session checkpoints <ref> | GET SESSIONS/<ref>/checkpoints | commands/helix/reference-commands.ts → lib/helix-session-api.ts | | helix session restore <ref> | POST SESSIONS/<ref>/restore {snapshotId?, onWorkspaceDrift?, partial?}; retried when the answer is 409 sandbox_stopping | commands/helix/restore-command.ts → lib/helix-session-api.ts, lib/sandbox-stopping-retry.ts | | helix session start <sandbox-id> (internal) | POST /api/sandbox/:id/session {mode, args?, cwd?, environment?} | commands/helix/session-commands.ts → lib/sandbox-api.ts | | helix models | GET /api/sandbox/helix/defaults | commands/helix/models.ts → lib/sandbox-api.ts | | helix models default <ids…>, --clear | PUT /api/sandbox/helix/defaults {models} (--clear sends []) | commands/helix/models.ts → lib/sandbox-api.ts | | helix doctor, helix smoke | POST /api/sandbox/run (fresh preset sandbox, torn down after), or POST /api/sandbox/:id/exec with --sandbox | commands/helix/doctor.ts → lib/sandbox-api.ts | | helix version | GET /api/sandbox/presets | commands/helix/doctor.ts → lib/sandbox-catalog.ts | | helix update | GET /api/sandbox/presets to name the pinned version, then exit 1 (NOT_SUPPORTED) | commands/helix/doctor.ts |

All source paths in this table are under mutagent-cli/src/.

`mutagent agent` verbs

| Verb | API call | CLI source | |---|---|---| | agent check <agent.md> | local, no API: compile and validate the folder | commands/agent/index.ts → lib/agent/local.ts | | agent pack <agent.md> --output <archive> | local, no API: write the package archive | commands/agent/index.ts → lib/agent/local.ts | | agent run <agent.md> <task…> | local, no API: runs the package with the local Helix binary; a slug argument is refused before any work | commands/agent/index.ts → lib/agent/local.ts | | agent deploy <agent.md> [--env] [--no-activate] [--idempotency-key] | compiles locally, then GET /api/helix-agent/capabilities, then POST /api/helix-agent/agents/{slug}/deployments {archiveBase64, archiveDigest, artifactDigest, archiveSize, environment?, activate, idempotencyKey} | commands/agent/index.ts → lib/agent/service.ts → lib/agent/remote.ts → lib/agent/sdk.ts | | agent activate <slug> --revision vN [--env] [--idempotency-key] | POST /api/helix-agent/agents/{slug}/activate {revision, environment?, idempotencyKey} | commands/agent/index.ts → lib/agent/remote.ts → lib/agent/sdk.ts | | agent list [--limit] [--cursor] [--include-archived] | GET /api/helix-agent/agents | commands/agent/index.ts → lib/agent/remote.ts → lib/agent/sdk.ts | | agent inspect <slug> [--env] [--limit] [--cursor] | GET /api/helix-agent/agents/{slug} (revisions, slots, sessions; --env filters on the client) | commands/agent/index.ts → lib/agent/remote.ts → lib/agent/sdk.ts | | agent inspect --operation <id> | GET /api/helix-agent/operations/{operationId} | lib/agent/remote.ts → lib/agent/sdk.ts | | agent retire <slug> [--env] | POST /api/helix-agent/agents/{slug}/retire {environment?} | commands/agent/index.ts → lib/agent/remote.ts → lib/agent/sdk.ts |

All source paths in this table are under mutagent-cli/src/. The route paths are the generated SDK's (mutagent-sdk/src/funcs/managed-agents-*.ts) and match the server routes in mutagent/src/modules/helix-agent/deployment/routes.ts.

Running a deployed agent is not an agent verb: it is mutagent helix agent @slug, which uses the same launch route as every cloud run (row above).

AI-first usage

Platform commands support --json with _directive (next-step guidance for agents) and _links (dashboard/API URLs). Cloud Helix runs stream native Helix output.

export MUTAGENT_API_KEY="mg_live_xxxx"   # Zero-config with env var

mutagent --help                          # Discover the surface
mutagent --version --json

mutagent workspaces list --json          # JSON output
mutagent providers list --models --json
mutagent usage --json

mutagent init --non-interactive          # Non-interactive mode
mutagent skills install                  # Install the skill so agents can self-serve

JSON Directive & Links

--json responses may include:

| Field | Meaning | |---|---| | _directive.renderedCard | Pre-formatted status card — agents must echo it verbatim in chat | | _directive.instruction | Self-contained next step for the agent | | _directive.next | Array of suggested follow-up commands | | _links | Dashboard / API URLs | | _compat | Compat metadata: cliVersion, skillVersion, skillMinCliVersion |

Exit codes and failures

One table for every command (EXIT_CODES in src/lib/errors.ts):

| Code | Meaning | |---|---| | 0 | Success | | 1 | Failure, usage errors included (unknown command or option, a missing argument) | | 2 | The API key expired or is invalid (a key from another service included) | | 3 | Not signed in, or no workspace selected |

Exit 0 means success and nothing else: under --json, success: true if and only if the exit code is 0. A failure under --json is one object on stdout:

{
  "success": false,
  "error": "What went wrong",
  "code": "UNKNOWN_OPTION",
  "suggestedAction": "Run: mutagent env ls --help",
  "_agentGuidance": {
    "helpCommand": "mutagent env ls --help",
    "fix": ["mutagent env ls --help"],
    "notes": [],
    "escalate": "Present only when a person has to act"
  }
}

In a terminal the same failure is Error: … on stderr, with the fix. Commands that forward a remote process (sandbox exec, a Helix run) exit with that process's own code.

License

Released under the Apache License 2.0.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme