@mutagent/cli 0.1.356 → 0.1.357

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +403 -319
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,72 +1,80 @@
1
- # MutagenT CLI
1
+ ![MutagenT](../assets/brand/mutagent-banner.svg)
2
2
 
3
- ```
4
- ███╗ ███╗██╗ ██╗████████╗ █████╗ ██████╗ ███████╗███╗ ██╗████████╗
5
- ████╗ ████║██║ ██║╚══██╔══╝██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝
6
- ██╔████╔██║██║ ██║ ██║ ███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║
7
- ██║╚██╔╝██║██║ ██║ ██║ ██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║
8
- ██║ ╚═╝ ██║╚██████╔╝ ██║ ██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║
9
- ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝
10
- ██████╗██╗ ██╗
11
- ██╔════╝██║ ██║
12
- ██║ ██║ ██║
13
- ██║ ██║ ██║
14
- ╚██████╗███████╗██║
15
- ╚═════╝╚══════╝╚═╝
16
- ```
3
+ # MutagenT CLI
17
4
 
18
5
  <p align="center">
19
6
  <a href="https://www.npmjs.com/package/@mutagent/cli"><img src="https://img.shields.io/npm/v/@mutagent/cli?style=for-the-badge&color=cb3837&logo=npm&logoColor=white" alt="npm"></a>
20
- <a href="https://bun.sh"><img src="https://img.shields.io/badge/Bun-1.0+-f472b6?style=for-the-badge&logo=bun&logoColor=white" alt="Bun"></a>
21
- <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-22+-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js"></a>
7
+ <a href="https://bun.sh"><img src="https://img.shields.io/badge/Bun-1.1+-f472b6?style=for-the-badge&logo=bun&logoColor=white" alt="Bun"></a>
8
+ <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-22.18+-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js"></a>
22
9
  <a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript"></a>
23
- <a href="#"><img src="https://img.shields.io/badge/License-Proprietary-ff6b6b?style=for-the-badge" alt="License: Proprietary"></a>
10
+ <a href="#"><img src="https://img.shields.io/badge/License-Apache_2.0-blue?style=for-the-badge" alt="License: Apache 2.0"></a>
24
11
  </p>
25
12
 
26
13
  <p align="center">
27
- <strong>Authenticate. Configure LLM providers. Install Helix.</strong>
14
+ <strong>Authenticate. Manage the platform. Run Helix locally and in the cloud.</strong>
28
15
  </p>
29
16
 
30
17
  ---
31
18
 
32
- ## What is MutagenT CLI?
19
+ MutagenT CLI is the command-line client for the MutagenT AI platform. It handles
20
+ authentication, BYOK LLM providers, workspace Environments, managed agents, cloud
21
+ sandboxes and Helix sessions, and the standalone Helix binary installer.
22
+
23
+ **Status:** all commands and flags below were verified against `mutagent --help`
24
+ (and each subcommand's `--help`) on this branch. `sandbox` is internal (everyday
25
+ use goes through `mutagent helix`); `trace` is not implemented in this binary —
26
+ it prints where to find it (`helix-cli trace`) and exits with an error.
27
+
28
+ [Context](#context) · [Concepts](#concepts) · [Components](#components) · [Configuration](#configuration) · [Reference](#reference)
29
+
30
+ ---
33
31
 
34
- MutagenT CLI is the command-line client for the **MutagenT AI platform**. It is the
35
- entry point that AI coding agents and developers use to authenticate, set up a
36
- project, manage BYOK LLM providers, check account usage, and install the
37
- standalone Helix binary.
32
+ ## Context
38
33
 
39
- Every command is **AI-first**: run any command with `--json` for machine-readable
40
- output, and install the bundled Claude Code skill so coding agents know how to
41
- drive the CLI without human hand-holding.
34
+ MutagenT CLI is the entry point AI coding agents and developers use to sign in,
35
+ configure a project, manage BYOK LLM provider keys, check usage, manage workspace
36
+ Environments (secrets for agent tools), package and deploy managed agents, and
37
+ install or run Helix. It is a thin, `--json`-first client over the MutagenT API
38
+ (the [backend server](../mutagent/README.md)); the generated
39
+ [`@mutagent/sdk`](../mutagent-sdk/README.md) is what most commands call underneath.
40
+ For where the CLI sits relative to the rest of the platform, see the
41
+ [root README's architecture section](../README.md#architecture).
42
42
 
43
- ### Key Features
43
+ ### Key features
44
44
 
45
- - **For scripts and agents**: commands support `--json` with `_directive` and `_links`. A `mutagent helix` run prints Helix's own output; `--json` does not change it
46
- - **One-Command Auth**: `mutagent login` handles signup, onboarding, and CLI authorization via browser OAuth (or an API key for CI)
47
- - **LLM providers (BYOK)**: Configure and test your own LLM provider keys (`mutagent providers`)
48
- - **Helix Installer**: `mutagent install helix` installs the standalone Helix binary into `~/.mutagent/bin` (no login needed)
49
- - **Claude Code Integration**: Install the CLI skill (`mutagent skills install`) and session-telemetry hooks (`mutagent hooks install`)
50
- - **Built-in Feedback**: `mutagent feedback send` reports bugs and product feedback, optionally with your coding-agent session transcript
51
- - **Bun-Native**: Built for speed with the Bun runtime (Node.js 22+ compatible)
45
+ - **AI-first**: every platform command supports `--json` with `_directive` and `_links`; a `mutagent helix` run streams Helix's own output unchanged
46
+ - **One-command auth**: `mutagent login` handles signup, onboarding and CLI authorization via browser OAuth (or an API key for CI)
47
+ - **LLM providers (BYOK)**: configure and test your own provider keys (`mutagent providers`), or copy them from a local Helix login (`mutagent providers mirror`)
48
+ - **Workspace Environments**: `mutagent env` holds the variables and secrets an agent's tools need, separate from LLM provider keys
49
+ - **Managed agents**: `mutagent agent` checks, packages, deploys and runs `agent.md` folders; `mutagent helix agent @slug` runs a deployed one in the cloud
50
+ - **Helix installer**: `mutagent install helix` installs the standalone Helix binary into `~/.mutagent/bin` (no login needed)
51
+ - **Claude Code integration**: install the CLI skill (`mutagent skills install`) and session-telemetry hooks (`mutagent hooks install`)
52
+ - **Built-in feedback**: `mutagent feedback send` reports bugs and product feedback, optionally with your coding-agent session transcript
52
53
 
53
54
  ---
54
55
 
55
- ## Interaction Flow Map
56
+ ## Concepts
56
57
 
57
- The active command surface and the typical routes through it.
58
+ - **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>`).
59
+ - **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.
60
+ - **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.
61
+ - **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).
62
+ - **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.
63
+ - **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.
64
+ - **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](#json-directive--links).
58
65
 
59
66
  ```mermaid
67
+ %%{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"}}}%%
60
68
  flowchart TD
61
69
  INSTALL["npm i -g @mutagent/cli"] --> AUTH_CHOICE{How to authenticate?}
62
70
 
63
71
  AUTH_CHOICE -->|Interactive / browser OAuth| LOGIN["mutagent login"]
64
72
  AUTH_CHOICE -->|Force browser| LOGIN_B["mutagent login --browser"]
65
- AUTH_CHOICE -->|CI / env var| ENV["export MUTAGENT_API_KEY=mt_...<br/>mutagent login --json"]
73
+ AUTH_CHOICE -->|CI / env var| ENV_AUTH["export MUTAGENT_API_KEY=mg_live_...<br/>mutagent login --json"]
66
74
 
67
75
  LOGIN --> INIT["mutagent init<br/>(.mutagentrc.json)"]
68
76
  LOGIN_B --> INIT
69
- ENV --> INIT
77
+ ENV_AUTH --> INIT
70
78
 
71
79
  INIT --> SETUP
72
80
 
@@ -90,7 +98,7 @@ flowchart TD
90
98
  subgraph PROVIDER_CMDS ["LLM providers (BYOK)"]
91
99
  PROV_LIST["mutagent providers list"]
92
100
  PROV_ADD["mutagent providers add"]
93
- PROV_TEST["mutagent providers test <id>"]
101
+ PROV_MIRROR["mutagent providers mirror"]
94
102
  end
95
103
 
96
104
  subgraph AGENT_TOOLING ["Coding-Agent Tooling"]
@@ -98,132 +106,235 @@ flowchart TD
98
106
  HOOKS["mutagent hooks install"]
99
107
  end
100
108
 
109
+ subgraph CLOUD ["Cloud execution"]
110
+ SANDBOX["mutagent sandbox"]
111
+ ENVIRONMENT["mutagent env"]
112
+ HELIX["mutagent helix"]
113
+ AGENT["mutagent agent"]
114
+ TRACE["mutagent trace<br/>(→ helix-cli)"]
115
+ end
116
+
101
117
  subgraph LIFECYCLE ["Helix & Feedback"]
102
118
  INSTALL_PKG["mutagent install helix"]
103
119
  FEEDBACK["mutagent feedback send"]
104
120
  end
105
121
  end
122
+
123
+ AUTH_CMDS ~~~ PLATFORM_CMDS ~~~ PROVIDER_CMDS
124
+ AGENT_TOOLING ~~~ CLOUD ~~~ LIFECYCLE
125
+
126
+ classDef default fill:#161b22,stroke:#444c56,color:#e6edf3
127
+ classDef surface fill:#1a3a5c,stroke:#4a90e2,color:#fff
128
+ classDef runtime fill:#2d4a2d,stroke:#4a9e4a,color:#fff
129
+ classDef tool fill:#2a1a4a,stroke:#bc8cff,color:#fff
130
+ classDef data fill:#4a3a2d,stroke:#cc9944,color:#fff
131
+ classDef external fill:#3a3a4a,stroke:#888,color:#e6edf3
132
+ class INSTALL,LOGIN,LOGIN_B,ENV_AUTH,INIT surface
133
+ class AUTH_CHOICE,AUTH_STATUS,AUTH_LOGOUT,CONFIG_LIST,CONFIG_SET_WS,CONFIG_SET_ORG,SKILLS,HOOKS tool
134
+ class SANDBOX,ENVIRONMENT,HELIX,AGENT,TRACE,PROV_LIST,PROV_ADD,PROV_MIRROR runtime
135
+ class WS_LIST,WS_GET,USAGE,INSTALL_PKG,FEEDBACK data
106
136
  ```
107
137
 
108
138
  ---
109
139
 
110
- ## Installation
111
-
112
- ### Using Bun (Recommended)
140
+ ## Components
113
141
 
114
- ```bash
115
- bun install -g @mutagent/cli
142
+ ```
143
+ mutagent-cli/
144
+ ├── src/
145
+ │ ├── bin/cli.ts # Commander entry point; registers every top-level command
146
+ │ ├── commands/ # One module per command (auth, config, workspaces, usage,
147
+ │ │ # init, skills, hooks/, install/, providers/, env/,
148
+ │ │ # agent/, helix/, sandbox/, feedback)
149
+ │ ├── lib/ # Config resolution, auth flow, SDK client, brand/TTY,
150
+ │ │ # agent packaging, installer, session API
151
+ │ ├── generated/ # Skill content baked from .claude/skills/mutagent-cli (sync-skill)
152
+ │ └── types/ # Shared types
153
+ ├── src/__tests__/ # Unit tests (5+ per subcommand: structure, happy, error, json, edge)
154
+ ├── tests/ # Integration + pipe tests, fixtures (agent-deployment example)
155
+ ├── docs/helix-surface-map.md # Earlier verb → API map; superseded by Command surface below
156
+ └── scripts/ # sync-skill.ts, build.ts, workspace-resolution check
116
157
  ```
117
158
 
118
- ### Using npm
159
+ Entry point: `src/bin/cli.ts`, built to `dist/bin/cli.js` (the `mutagent` bin).
119
160
 
120
- ```bash
121
- npm install -g @mutagent/cli
122
- ```
161
+ ### Commands (package scripts)
123
162
 
124
- ### Standalone Binary
163
+ | Command | What it does |
164
+ |---|---|
165
+ | `bun run dev` | Runs the CLI from source (`sync-skill` then `src/bin/cli.ts`) |
166
+ | `bun run build` | Builds `dist/` |
167
+ | `bun run build:binary` | Builds the standalone binary for the host platform; `build:binary:<os>-<arch>` targets one explicitly |
168
+ | `bun run type-check` | `tsc --noEmit` for `src/` and the test tsconfig |
169
+ | `bun run lint` / `lint:fix` | ESLint over `src` (excluding `__tests__`) and `src/__tests__` |
170
+ | `bun run test` | `bun test src/` — the verification gate for this package |
171
+ | `bun run test:integration` | `bun test tests/pipe/` (30s timeout) |
172
+ | `bun run verify` | workspace-resolution check + lint + type-check + build |
173
+
174
+ Run `bun run` with no arguments in `mutagent-cli/` to list every script. Never
175
+ run `bun test` at the monorepo root — this package's suite must run scoped
176
+ (`cd mutagent-cli && bun run test`).
125
177
 
126
- ```bash
127
- # No Bun or Node.js required
128
- curl -fsSL https://github.com/mutagent/cli/releases/latest/download/mutagent-$(uname -s)-$(uname -m) -o mutagent
129
- chmod +x mutagent && sudo mv mutagent /usr/local/bin/
130
- ```
178
+ ### Prerequisites
131
179
 
132
- ### Verify Installation
180
+ - [Bun](https://bun.sh) >= 1.1.0
181
+ - Node.js >= 22.18 (fallback runtime; Bun is primary)
182
+
183
+ ### Setup
133
184
 
134
185
  ```bash
135
- mutagent --version
186
+ git clone https://github.com/architech-printworks/mutagent-monorepo.git
187
+ cd mutagent-monorepo
188
+ bun install
189
+ cd mutagent-cli
136
190
  ```
137
191
 
138
- ---
192
+ ### Reference material
139
193
 
140
- ## Quick Start
194
+ - [Command Reference](#command-reference) below — every command, verified against `--help`
195
+ - [Command surface](#command-surface) — the `helix` and `agent` trees mapped to API routes and CLI source
196
+ - [tests/fixtures/agent-deployment](tests/fixtures/agent-deployment) — a complete `agent.md` example
141
197
 
142
- ### 1. Authenticate
143
-
144
- ```bash
145
- # End users — browser OAuth (handles signup, onboarding, CLI authorization)
146
- mutagent login
198
+ ---
147
199
 
148
- # Force browser flow (skip method prompt)
149
- mutagent login --browser
200
+ ## Configuration
150
201
 
151
- # CI / AI agent — set env var then run (no prompts, no browser)
152
- export MUTAGENT_API_KEY="mt_live_xxxx"
153
- mutagent login --json
202
+ ### Environment variables
203
+
204
+ `Read at` cites this branch's `mutagent-cli/src`. `Secret` marks values that must
205
+ never be logged or committed. None of these are required to run `mutagent --help`;
206
+ `MUTAGENT_API_KEY` is required for non-interactive/CI login.
207
+
208
+ | Variable | Required | Default | Read at | Secret | Purpose |
209
+ |---|---|---|---|---|---|
210
+ | `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 |
211
+ | `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 |
212
+ | `MUTAGENT_APP_URL` | No | `https://app.mutagent.io` | `src/lib/ui-links.ts:17` | No | Dashboard base URL used in printed links |
213
+ | `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 |
214
+ | `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 |
215
+ | `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 |
216
+ | `NO_COLOR` | No | unset | `src/lib/tty.ts:19` | No | Any non-empty value disables color and interactive-TTY behavior |
217
+ | `MUTAGENT_NO_BANNER` | No | unset | `src/lib/brand.ts:105` | No | `1` disables the CLI's banner |
218
+ | `COLORTERM` | No (set by the terminal) | unset | `src/lib/brand.ts:82` | No | `truecolor`/`24bit` enables the gradient banner |
219
+ | `MUTAGENT_DEBUG` | No | unset | `src/lib/sdk-debug.ts:36` | No | Truthy value enables the generated SDK's debug logging |
220
+ | `MUTAGENT_SANDBOX_TOKEN_FILE` | No | internal cache path | `src/lib/sandbox-token.ts:79` | No | Overrides where the cached sandbox operator token is stored |
221
+ | `MUTAGENT_SUBAGENTS_BUNDLE_DIR` | No | none | `src/commands/helix/agent-argv.ts:457` | No | Extra root directory searched for subagent bundles |
222
+ | `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` |
223
+ | `PI_CODING_AGENT_DIR` | No | `~/.omp/agent` | `src/lib/transcript.ts:120` | No | Local OMP/Pi agent directory used for transcript lookups |
224
+ | `MUTAGENT_HELIX_CHANNEL` | No | `latest` | `src/lib/installer-helix.ts:294` | No | Release channel for `mutagent install helix` when `--channel` is not passed |
225
+ | `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) |
226
+ | `MUTAGENT_INSTALL_DIR` | No | `~/.mutagent/bin` | `src/lib/installer-helix.ts:301-302` | No | Install directory for `mutagent install helix` |
227
+ | `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` |
228
+ | `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) |
229
+ | `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 |
230
+ | `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 |
231
+ | `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 |
232
+ | `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 |
233
+ | `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 |
234
+ | `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 |
235
+ | `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 |
236
+ | `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 |
237
+
238
+ `MUTAGENT_HELIX_BIN` and `MUTAGENT_BUN_BIN` are documented by `mutagent agent --help`
239
+ (select a local Helix binary and Bun binary for `agent run`/compilation) but are
240
+ resolved inside the `@mutagent/agents` package, not this package's `src/` — they
241
+ are not in the table above for that reason.
242
+
243
+ An example file with placeholder values is at
244
+ [`.env.example`](.env.example); the CLI does not auto-load a `.env` file itself,
245
+ but Bun does when you run it with `bun run dev` from this directory.
246
+
247
+ ### RC file
248
+
249
+ `mutagent init` writes `.mutagentrc.json` (skipped if one already exists):
154
250
 
155
- # Back-compat alias — behaves identically to `mutagent login`
156
- mutagent auth login
251
+ ```json
252
+ {
253
+ "endpoint": "https://api.mutagent.io",
254
+ "format": "table"
255
+ }
157
256
  ```
158
257
 
159
- > `mutagent login` is the canonical command. `mutagent auth login` is preserved
160
- > as a back-compat alias; both behave identically.
258
+ `mutagent config set workspace <id>` / `mutagent config set org <id>` add
259
+ `defaultWorkspace` / `defaultOrganization` to the same file.
161
260
 
162
- ### 2. Initialize Your Project
261
+ ### Global config
163
262
 
164
- ```bash
165
- mutagent init # Interactive setup — writes .mutagentrc.json
166
- mutagent init --non-interactive # CLI-only defaults, no prompts
263
+ Credentials are stored in `~/.config/mutagent/credentials.json`, created by
264
+ `mutagent login`. No ports: this package is a CLI, not a server.
167
265
 
168
- # Confirm state
169
- mutagent auth status
170
- ```
266
+ ---
267
+
268
+ ## Reference
171
269
 
172
- ### 3. Configure LLM providers (BYOK)
270
+ ### Installation
173
271
 
174
272
  ```bash
175
- mutagent providers list # List configured LLM providers
176
- mutagent providers list --models # Show available models per LLM provider
177
- mutagent providers add # Add an LLM provider key (prompts for values)
178
- mutagent providers test <provider-id> # Verify connectivity
273
+ # Bun (recommended)
274
+ bun install -g @mutagent/cli
275
+
276
+ # npm
277
+ npm install -g @mutagent/cli
179
278
  ```
180
279
 
181
- ### 4. Install Helix
280
+ Standalone binary: build one from this monorepo with `bun run build:binary` in
281
+ `mutagent-cli/` (per-target scripts also exist for Linux, macOS and Windows).
182
282
 
183
283
  ```bash
184
- mutagent install helix # The standalone Helix binary → ~/.mutagent/bin/helix
185
- mutagent install helix --channel candidate # The candidate build
284
+ mutagent --version # Verify installation
186
285
  ```
187
286
 
188
- ### 5. Wire Up Your Coding Agent
287
+ ### Quick start
189
288
 
190
289
  ```bash
191
- mutagent skills install # Install the MutagenT CLI skill for AI agents
192
- mutagent hooks install # Install Claude Code session-telemetry hooks
290
+ # 1. Authenticate
291
+ mutagent login # Browser OAuth (recommended)
292
+ mutagent login --browser # Force browser flow
293
+ export MUTAGENT_API_KEY="mg_live_xxxx" && mutagent login --json # CI / AI agent
294
+ mutagent auth login # Back-compat alias for `mutagent login`
295
+
296
+ # 2. Initialize your project
297
+ mutagent init # Writes .mutagentrc.json + installs the CLI skill
298
+ mutagent auth status # Confirm state
299
+
300
+ # 3. Configure LLM providers (BYOK)
301
+ mutagent providers mirror # Copy keys from a local Helix login, or:
302
+ mutagent providers add # Add one manually
303
+ mutagent providers test <provider-id> # Verify connectivity
304
+
305
+ # 4. Install Helix
306
+ mutagent install helix # → ~/.mutagent/bin/helix
307
+ mutagent install helix --channel candidate # Candidate build
308
+
309
+ # 5. Wire up your coding agent
310
+ mutagent skills install # Installs .claude/skills/mutagent-cli/SKILL.md
311
+ mutagent hooks install # Installs session-telemetry hooks
193
312
  ```
194
313
 
195
- ---
196
-
197
- ## Commands Reference
314
+ `mutagent login` is the canonical command; `mutagent auth login` is a back-compat
315
+ alias, both identical.
198
316
 
199
- The active command surface:
317
+ ### Command reference
200
318
 
201
- `login` · `auth` · `config` · `workspaces` · `providers` · `usage` · `init` · `skills` · `hooks` · `install` · `feedback`
319
+ The active command surface: `login` · `auth` · `config` · `workspaces` · `providers` ·
320
+ `usage` · `init` · `skills` · `hooks` · `install` · `sandbox` · `env` · `helix` ·
321
+ `agent` · `trace` · `feedback`.
202
322
 
203
323
  Run `mutagent <command> --help` for the authoritative, current flag list — the CLI
204
324
  is the source of truth for flags.
205
325
 
206
- ### Global Options
326
+ #### Global options
207
327
 
208
328
  | Option | Description |
209
- |--------|-------------|
210
- | `--json` | Output results as JSON with `_directive` + `_links` |
211
- | `--non-interactive` | Disable all interactive prompts (also: `CI=true`) |
212
- | `--api-key <key>` | Override API key for this command |
213
- | `--endpoint <url>` | Override API endpoint |
214
- | `--help` | Show help with examples and workflow hints |
215
- | `-v, --version` | Show CLI version |
216
-
217
- ### Environment Variables
218
-
219
- | Variable | Description |
220
- |----------|-------------|
221
- | `MUTAGENT_API_KEY` | API key (skips interactive login) |
222
- | `MUTAGENT_ENDPOINT` | Custom API endpoint |
223
- | `MUTAGENT_NON_INTERACTIVE=true` | Non-interactive mode |
224
- | `CI=true` | Enables non-interactive mode |
329
+ |---|---|
330
+ | `--json` | Output results as JSON (for AI agents) |
331
+ | `--api-key <key>` | Mutagent API key for this command |
332
+ | `--endpoint <url>` | Mutagent server endpoint for this command |
333
+ | `--non-interactive` | Disable interactive prompts (for CI/AI agents) |
334
+ | `-h, --help` | Display help for command |
335
+ | `-v, --version` | CLI version (only before a subcommand) |
225
336
 
226
- ### Authentication (`login` / `auth`)
337
+ #### Authentication (`login` / `auth`)
227
338
 
228
339
  ```bash
229
340
  mutagent login # Browser OAuth (recommended)
@@ -231,27 +342,26 @@ mutagent login --browser # Force browser flow
231
342
  mutagent login --json # Non-interactive (uses MUTAGENT_API_KEY)
232
343
 
233
344
  mutagent auth login # Back-compat alias for `mutagent login`
234
- mutagent auth status # Check auth + workspace + onboarding state
345
+ mutagent auth status # Sign-in state, endpoint and active workspace
235
346
  mutagent auth logout # Clear stored credentials
236
347
  ```
237
348
 
238
- ### Configuration (`config`)
349
+ #### Configuration (`config`)
239
350
 
240
351
  ```bash
241
352
  mutagent config list # List all config values
242
- mutagent config get <key> # Get a value (apiKey, endpoint, format, timeout, defaultWorkspace, defaultOrg)
353
+ mutagent config get <key> # apiKey, endpoint, format, timeout, defaultWorkspace, defaultOrganization
243
354
  mutagent config set workspace <id> # Set default workspace
244
355
  mutagent config set org <id> # Set default organization
245
356
  ```
246
357
 
247
- ### Project Setup (`init`)
358
+ #### Project setup (`init`)
248
359
 
249
360
  ```bash
250
- mutagent init # Interactive wizard — writes .mutagentrc.json
251
- mutagent init --non-interactive # Skip prompts (CLI-only defaults)
361
+ mutagent init # Writes .mutagentrc.json + installs the CLI skill. Never prompts.
252
362
  ```
253
363
 
254
- ### Workspaces (`workspaces`, read-only)
364
+ #### Workspaces (`workspaces`, read-only)
255
365
 
256
366
  ```bash
257
367
  mutagent workspaces list # List all workspaces
@@ -259,45 +369,70 @@ mutagent workspaces list --limit 20 --offset 0
259
369
  mutagent workspaces get <id> # Workspace details
260
370
  ```
261
371
 
262
- ### LLM providers (`providers`)
372
+ Create or change workspaces in the dashboard (https://app.mutagent.io).
373
+
374
+ #### LLM providers (`providers`)
263
375
 
264
376
  ```bash
377
+ mutagent providers mirror # Copy API keys from your local Helix login store
265
378
  mutagent providers list # List configured LLM providers
266
379
  mutagent providers list --models # Show available models per LLM provider
267
380
  mutagent providers get <id> # LLM provider details
268
381
  mutagent providers test <id> # Test LLM provider connectivity
269
382
 
270
383
  # Manage keys
271
- mutagent providers add # Add an LLM provider (prompts for values; --scope, --base-url, --set-default)
384
+ mutagent providers add # Add a provider (--provider, --name, --api-key, --scope, --base-url, --set-default)
272
385
  mutagent providers update <id> --name "New name" --active true
273
386
  mutagent providers delete <id> --force
274
387
  ```
275
388
 
276
- ### Usage (`usage`)
389
+ LLM provider types: `openai`, `anthropic`, `google`, `moonshot`, `glm`, `deepseek`,
390
+ `xai`, `azure`, `vertex`, `bedrock`, `custom`.
391
+
392
+ #### Workspace Environments (`env`)
277
393
 
278
394
  ```bash
279
- mutagent usage # Show account usage + LLM provider status
280
- mutagent usage --json # Machine-readable
395
+ mutagent env ls # List the workspace's Environments
396
+ mutagent env set demo GREETING=hello --secret GITHUB_TOKEN=ghp_…
397
+ mutagent env set staging --from-file .env.staging --secrets-from-file .env.staging.secrets
398
+ mutagent env show demo # Entry names + fingerprints — never a value
399
+ mutagent env unset demo GREETING
400
+ mutagent env rm demo --force
401
+ mutagent helix --env demo -p "check the deploy" # Load it into a Helix cloud run
281
402
  ```
282
403
 
283
- ### Skills & Hooks (Claude Code)
404
+ An Environment holds the variables and secrets an agent's tools need, distinct
405
+ from LLM provider keys (`mutagent providers`) — a variable named like a provider
406
+ key (`ANTHROPIC_API_KEY`, …) is refused unless `--allow-provider-key`. `set`
407
+ merges into an existing Environment (PATCH); `--replace` overwrites it (PUT) and
408
+ removes entries you don't name. Names: Environments use letters, digits, `.`, `_`
409
+ and `-` (up to 64 chars); variables use `A-Z`, `0-9` and `_`, not starting with a
410
+ digit. An Environment holds up to 64 KiB. Requires a workspace
411
+ (`mutagent config set workspace <id>`).
412
+
413
+ #### Usage (`usage`)
284
414
 
285
415
  ```bash
286
- # Install the MutagenT CLI skill so coding agents know how to drive the CLI
287
- mutagent skills install # Creates .claude/skills/mutagent-cli/SKILL.md
416
+ mutagent usage # Account usage + LLM provider status
417
+ mutagent usage --json # Machine-readable
418
+ ```
288
419
 
289
- # Install session-telemetry hooks (safe merge into .claude/settings.local.json)
290
- mutagent hooks install
291
- mutagent hooks install --cwd ./path # Target a specific directory
420
+ #### Skills & hooks (Claude Code)
421
+
422
+ ```bash
423
+ mutagent skills install # Creates .claude/skills/mutagent-cli/SKILL.md
424
+ mutagent hooks install # Merges hooks into .claude/settings.local.json (11 events)
425
+ mutagent hooks install --cwd ./path # Target a specific directory
426
+ mutagent hooks import <files...> # Upload Helix session transcripts as traces
292
427
  ```
293
428
 
294
- ### Managed Agents (`agent`, `helix agent @slug`)
429
+ #### Managed agents (`agent`, `helix agent @slug`)
295
430
 
296
431
  A managed agent is a folder whose entry file is `agent.md`: YAML frontmatter,
297
432
  then the standing prompt. The base fields (`name`, `description`, `model`,
298
- `thinking`, `tools`, `disallowed_tools`, `skills`) are a local brief; one
299
- optional `harness:` block holds the deployment settings (tools, skills, files,
300
- bindings, runtime). A complete example is in
433
+ `thinking`, `tools`, `disallowed_tools`, `skills`) are a local brief; one optional
434
+ `harness:` block holds the deployment settings (tools, skills, files, bindings,
435
+ runtime). A complete example is in
301
436
  [tests/fixtures/agent-deployment](tests/fixtures/agent-deployment).
302
437
 
303
438
  ```bash
@@ -322,10 +457,11 @@ mutagent agent list
322
457
  it in the cloud. The receipt is one JSON line on stderr; its reference is what
323
458
  `mutagent helix session` commands take.
324
459
  - `agent run` runs a local `agent.md` on this machine with the local Helix binary
325
- (`mutagent install helix` puts one at `~/.mutagent/bin/helix`; `MUTAGENT_HELIX_BIN` selects another) and creates nothing in the workspace.
460
+ (`mutagent install helix` puts one at `~/.mutagent/bin/helix`; `MUTAGENT_HELIX_BIN`
461
+ selects another) and creates nothing in the workspace.
326
462
  - Compilation requires Bun 1.3.14 on `PATH` or `MUTAGENT_BUN_BIN`.
327
463
 
328
- ### Helix Installer (`install`)
464
+ #### Helix installer (`install`)
329
465
 
330
466
  ```bash
331
467
  mutagent install helix # latest channel
@@ -335,55 +471,70 @@ mutagent install helix --json # binaryPath, version, sha256, onPa
335
471
 
336
472
  `mutagent install helix` does what `curl -fsSL https://install.mutagent.io/helix | bash`
337
473
  does: it downloads `helix-<os>-<arch>` (macOS or Linux, x64 or arm64) from
338
- `https://install.mutagent.io/<channel>/`, verifies it against `checksums.txt` from the
339
- same origin, writes `~/.mutagent/bin/helix` with the `mutagent-helix` alias, and runs
340
- `helix --version`. No login is needed. Shell rc files are never changed: when the
341
- directory is not on `PATH`, the line to add is printed. When you are signed in, the
342
- CLI also records the install activation, best-effort; `--json` reports it as
343
- `telemetry` (`sent`, `skipped` or `failed`).
344
-
345
- | Environment variable | Effect |
346
- |---|---|
347
- | `MUTAGENT_HELIX_CHANNEL` | `latest` or `candidate` when `--channel` is not passed |
348
- | `MUTAGENT_INSTALL_HOST` | Install host (default `https://install.mutagent.io`) |
349
- | `MUTAGENT_INSTALL_DIR` | Install directory (default `~/.mutagent/bin`) |
474
+ `https://install.mutagent.io/<channel>/`, verifies it against `checksums.txt` from
475
+ the same origin, writes `~/.mutagent/bin/helix` with the `mutagent-helix` alias,
476
+ and runs `helix --version`. No login is needed. Shell rc files are never changed:
477
+ when the directory is not on `PATH`, the line to add is printed. When you are
478
+ signed in, the CLI also records the install activation, best-effort; `--json`
479
+ reports it as `telemetry` (`sent`, `skipped` or `failed`).
480
+
481
+ `diagnostics` and `evaluator` are not install targets: both skills ship inside
482
+ helix — passing either name fails with `INVALID_ARGUMENTS` naming `helix` instead.
350
483
 
351
- `diagnostics` and `evaluator` are not install targets: both skills ship inside helix.
484
+ See the [Configuration](#configuration) table above for `MUTAGENT_HELIX_CHANNEL`,
485
+ `MUTAGENT_INSTALL_HOST` and `MUTAGENT_INSTALL_DIR`.
352
486
 
353
- ### Feedback (`feedback`)
487
+ #### Sandbox management (`sandbox`, internal)
488
+
489
+ Everyday use goes through `mutagent helix`, which spawns a sandbox implicitly.
490
+ `mutagent sandbox` manages one directly — useful for scripted or long-lived work:
354
491
 
355
492
  ```bash
356
- # Report a bug or send product feedback (login-gated)
357
- mutagent feedback send "describe what went wrong" --category cli
493
+ mutagent sandbox presets # Presets `mutagent helix --preset` can name
494
+ mutagent sandbox providers # Providers `mutagent helix --sandbox-provider` can name
495
+ mutagent sandbox preflight --image alpine:3.20 # Would this definition run?
496
+ mutagent sandbox spawn --image alpine:3.20 --detach
497
+ mutagent sandbox ls
498
+ mutagent sandbox status sbx_1
499
+ mutagent sandbox exec --sandbox sbx_1 -- bun test
500
+ mutagent sandbox attach sbx_1 --since 412
501
+ mutagent sandbox traces sbx_1 # Spans recorded for a sandbox
502
+ mutagent sandbox rm sbx_1 --force
503
+ ```
358
504
 
359
- # Lifecycle-stage feedback
360
- mutagent feedback send "eval gate unclear" --category stage:evaluate
505
+ `exec` without `--sandbox` runs one command in a fresh, one-shot sandbox and
506
+ removes it; `spawn` leaves a sandbox running for `attach`/`exec --sandbox`. A
507
+ sandbox idle 15 minutes is stopped (an interactive Helix session in it is
508
+ checkpointed first); `mutagent helix session restore <reference>` rebuilds it.
509
+ Requires a workspace (`mutagent config set workspace <id>`).
510
+
511
+ #### Feedback (`feedback`)
361
512
 
362
- # Link to a session and attach your coding-agent transcript
513
+ ```bash
514
+ mutagent feedback send "describe what went wrong" --category cli
515
+ mutagent feedback send "eval gate unclear" --category stage:evaluate
363
516
  mutagent feedback send "the CLI crashed on init" \
364
517
  --category cli --session <session-id> --attach-transcript
365
518
  ```
366
519
 
367
520
  | Flag | Description |
368
- |------|-------------|
521
+ |---|---|
369
522
  | `<feedback>` | Feedback body / content (required, ≤10000 chars) |
370
523
  | `--title <string>` | Optional 5–8 word summary of the session timeline |
371
524
  | `--category <value>` | `cli` (default) · `helix` · `stage:<spec\|build\|evaluate\|diagnose\|optimize>` |
372
525
  | `--session <id>` | Link feedback to a session id (server `sessionId`) |
373
526
  | `--attach-transcript [path]` | Attach the coding-agent session JSONL (bare = auto-detect newest) |
374
527
 
375
- ---
528
+ `--attach-transcript` uploads the full session JSONL (source code, absolute
529
+ paths, repo names, internal hostnames) — use it only when explicitly asked to.
376
530
 
377
- ## Command surface
531
+ ### Command surface
378
532
 
379
- The `mutagent helix` and `mutagent agent` trees as the CLI registers them, and the API each verb
380
- calls. Line anchors are to origin/main `0b4f9ce11` (17 Sep 2026); paths are repository-relative.
381
- For how each cloud verb maps to the local `helix` binary, see
382
- [docs/helix-surface-map.md](docs/helix-surface-map.md). That map was read from `4488d23b0`
383
- (12 Sep 2026) and predates the launch route, the reference-addressed session verbs and managed
384
- agents; where it and this section disagree, this section follows the source.
533
+ The `mutagent helix` and `mutagent agent` trees and their API routes. The command
534
+ definitions in [src/commands](src/commands/) are the source of truth.
385
535
 
386
536
  ```mermaid
537
+ %%{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"}}}%%
387
538
  flowchart LR
388
539
  ROOT["mutagent"] --> HX["helix"]
389
540
  ROOT --> AG["agent"]
@@ -420,126 +571,131 @@ flowchart LR
420
571
  AG --> ALIST["list"]
421
572
  AG --> AINSPECT["inspect"]
422
573
  AG --> ARETIRE["retire"]
574
+
575
+ classDef default fill:#161b22,stroke:#444c56,color:#e6edf3
576
+ classDef surface fill:#1a3a5c,stroke:#4a90e2,color:#fff
577
+ classDef runtime fill:#2d4a2d,stroke:#4a9e4a,color:#fff
578
+ classDef tool fill:#2a1a4a,stroke:#bc8cff,color:#fff
579
+ classDef data fill:#4a3a2d,stroke:#cc9944,color:#fff
580
+ classDef external fill:#3a3a4a,stroke:#888,color:#e6edf3
581
+ class ROOT,HX,AG surface
582
+ class HXRUN,HXAGENT,HXSESSION,HXAGENTDEF,HXAGENTSLUG,ARUN,ADEPLOY,AACTIVATE runtime
583
+ class HXMODELS,HXDOCTOR,HXSMOKE,HXVERSION,MDEFAULT,ACHECK,APACK tool
584
+ class SLS,SATTACH,SSEND,SSIGNAL,SCLOSE,SCHECKPOINT,SCHECKPOINTS,SRESTORE,SSTART,ALIST,AINSPECT,ARETIRE data
585
+ class HXUPDATE external
423
586
  ```
424
587
 
425
- Registration: `mutagent-cli/src/bin/cli.ts:243` (`helix`) and `:252` (`agent`);
426
- `mutagent-cli/src/commands/helix/index.ts:81-87` attaches `agent`, `session`, `models`, `doctor`,
427
- `smoke`, `version` and `update`; `mutagent-cli/src/commands/helix/session-commands.ts:55-63`
428
- attaches the session verbs; `mutagent-cli/src/commands/agent/index.ts:32-108` declares the
588
+ Registration: `mutagent-cli/src/bin/cli.ts` registers `helix` and `agent`;
589
+ `mutagent-cli/src/commands/helix/index.ts` attaches `agent`, `session`, `models`,
590
+ `doctor`, `smoke`, `version` and `update`; `mutagent-cli/src/commands/helix/session-commands.ts`
591
+ attaches the session verbs; `mutagent-cli/src/commands/agent/index.ts` declares the
429
592
  `agent` verbs.
430
593
 
431
- ### Credentials
594
+ #### Credentials
432
595
 
433
596
  The two trees authenticate differently.
434
597
 
435
- - **`mutagent helix …`** goes through `requestJson` (`mutagent-cli/src/lib/sandbox-api.ts:606`).
436
- Each request carries `Authorization: Bearer <operator token>` and `x-workspace-id`
437
- (`sandbox-api.ts:391`, `:490-495`). The operator token is minted from the platform API key by
438
- `POST /api/sandbox/token` (`mutagent-cli/src/lib/sandbox-token.ts:259-260`) and cached; a 401
439
- drops the cached token and mints once more (`sandbox-api.ts:462-467`).
598
+ - **`mutagent helix …`** goes through `requestJson` (`mutagent-cli/src/lib/sandbox-api.ts`).
599
+ Each request carries `Authorization: Bearer <operator token>` and `x-workspace-id`.
600
+ The operator token is minted from the platform API key by `POST /api/sandbox/token`
601
+ (`mutagent-cli/src/lib/sandbox-token.ts`) and cached; a 401 drops the cached
602
+ token and mints once more.
440
603
  - **`mutagent agent …`** (the remote verbs) goes through the generated SDK client
441
- `sdk.helixAgentDeployments` with the platform API key and an `x-workspace-id` header, and no
442
- token exchange (`mutagent-cli/src/lib/agent/sdk.ts:61`, `:107-112`). The server mounts these
443
- routes under `/api/helix-agent` (`mutagent/src/modules/helix-agent/deployment/module.ts:47`).
604
+ `sdk.managedAgents` with the platform API key and an `x-workspace-id` header, and
605
+ no token exchange (`mutagent-cli/src/lib/agent/sdk.ts`). The server mounts these
606
+ routes under `/api/helix-agent` (`mutagent/src/modules/helix-agent/deployment/module.ts`).
444
607
 
445
- ### `mutagent helix` verbs
608
+ #### `mutagent helix` verbs
446
609
 
447
610
  `<ref>` is a session reference (`hs1_…`). `SESSIONS` is `/api/sandbox/helix/sessions`
448
- (`mutagent-cli/src/lib/helix-session-api.ts:40`).
611
+ (`mutagent-cli/src/lib/helix-session-api.ts`).
449
612
 
450
613
  | Verb | API call | CLI source |
451
614
  |---|---|---|
452
- | `helix [argv…]` (classic arm; `--prime` = prime arm) | `POST SESSIONS` (launch), then the attach loop below | `commands/helix/index.ts:65-79` → `commands/helix/run-cloud.ts:44-48` → `lib/helix-session-api.ts:117-118` |
453
- | `helix … --sandbox <id>` (internal) | `POST /api/sandbox/:id/session`, then the attach loop | `commands/helix/run-cloud.ts:42-43` → `lib/sandbox-api.ts:741-749` |
454
- | 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:107-118`; `lib/helix-session-api.ts:121-144` |
455
- | `helix --version`, `-v` | `GET /api/sandbox/presets` (the preset description, not a live probe) | `commands/helix/index.ts:67-69` → `commands/helix/doctor.ts:280-306` → `lib/sandbox-catalog.ts:34` |
456
- | `helix agent <definition> …` | `POST SESSIONS` with `arm: agent` (or `POST /api/sandbox/:id/session` with `--sandbox`), then the attach loop | `commands/helix/agent.ts:114-140` → `commands/helix/run-cloud.ts:20-62` |
457
- | `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:99-111` → `commands/helix/managed-agent.ts:54-90` → `commands/helix/run-cloud.ts:76-105` |
458
- | `helix session ls` | `GET SESSIONS[?limit=&cursor=]` | `commands/helix/session-commands.ts:280` → `lib/helix-session-api.ts:76-84` |
459
- | `helix session ls <sandbox-id>` (internal) | `GET /api/sandbox/:id/sessions` | `commands/helix/session-commands.ts:261-262` → `lib/sandbox-api.ts:805-806` |
460
- | `helix session attach <ref>` | `GET SESSIONS/<ref>/stream[?since=]` | `commands/helix/session-commands.ts:347-356` → `lib/helix-session-api.ts:140-144` |
461
- | `helix session send <ref>` | `POST SESSIONS/<ref>/input` `{line}` | `commands/helix/send.ts:107` → `lib/helix-session-api.ts:121-125` |
462
- | `helix session send <id> --session <sid>` (internal) | `POST /api/sandbox/:id/input` `{sessionId, line}` | `commands/helix/send.ts:125` → `lib/sandbox-api.ts:707-708` |
463
- | `helix session signal <ref>` | `POST SESSIONS/<ref>/signal` `{signal}` (default `SIGINT`) | `commands/helix/signal.ts:100` → `lib/helix-session-api.ts:134-138` |
464
- | `helix session signal <id> --session <sid>` (internal) | `POST /api/sandbox/:id/signal` `{sessionId, signal}` | `commands/helix/signal.ts:118` → `lib/sandbox-api.ts:726-727` |
465
- | `helix session close-input <ref>` | `POST SESSIONS/<ref>/close-input` | `commands/helix/reference-commands.ts:91` → `lib/helix-session-api.ts:128-132` |
466
- | `helix session checkpoint <ref>` | `POST SESSIONS/<ref>/checkpoint` | `commands/helix/session-commands.ts:398` → `lib/helix-session-api.ts:86-90` |
467
- | `helix session checkpoint <id> --session <sid>` (internal) | `POST /api/sandbox/:id/checkpoint` | `commands/helix/session-commands.ts:407` → `lib/sandbox-checkpoints.ts:140-141` |
468
- | `helix session checkpoints <ref>` | `GET SESSIONS/<ref>/checkpoints` | `commands/helix/reference-commands.ts:39` → `lib/helix-session-api.ts:93-95` |
469
- | `helix session restore <ref>` | `POST SESSIONS/<ref>/restore` `{snapshotId?, onWorkspaceDrift?, partial?}`; retried when the answer is 409 `sandbox_stopping` | `commands/helix/restore-command.ts:85-95` → `lib/helix-session-api.ts:98-108`, `lib/sandbox-stopping-retry.ts:21-27` |
470
- | `helix session start <sandbox-id>` (internal) | `POST /api/sandbox/:id/session` `{mode, args?, cwd?, environment?}` | `commands/helix/session-commands.ts:139-150` → `lib/sandbox-api.ts:741-749` |
471
- | `helix models` | `GET /api/sandbox/helix/defaults` | `commands/helix/models.ts:85` → `lib/sandbox-api.ts:780-781` |
472
- | `helix models default <ids…>`, `--clear` | `PUT /api/sandbox/helix/defaults` `{models}` (`--clear` sends `[]`) | `commands/helix/models.ts:138` → `lib/sandbox-api.ts:785-787` |
473
- | `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:135`, `:179`, `:308-327` → `lib/sandbox-api.ts:692-693`, `:753-754` |
474
- | `helix version` | `GET /api/sandbox/presets` | `commands/helix/doctor.ts:263-268`, `:301-302` → `lib/sandbox-catalog.ts:34` |
475
- | `helix update` | `GET /api/sandbox/presets` to name the pinned version, then exit 2 | `commands/helix/doctor.ts:210-220` |
615
+ | `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` |
616
+ | `helix … --sandbox <id>` (internal) | `POST /api/sandbox/:id/session`, then the attach loop | `commands/helix/run-cloud.ts` → `lib/sandbox-api.ts` |
617
+ | 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` |
618
+ | `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` |
619
+ | `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` |
620
+ | `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` |
621
+ | `helix session ls` | `GET SESSIONS[?limit=&cursor=]` | `commands/helix/session-commands.ts` → `lib/helix-session-api.ts` |
622
+ | `helix session ls <sandbox-id>` (internal) | `GET /api/sandbox/:id/sessions` | `commands/helix/session-commands.ts` → `lib/sandbox-api.ts` |
623
+ | `helix session attach <ref>` | `GET SESSIONS/<ref>/stream[?since=]` | `commands/helix/session-commands.ts` → `lib/helix-session-api.ts` |
624
+ | `helix session send <ref>` | `POST SESSIONS/<ref>/input` `{line}` | `commands/helix/send.ts` → `lib/helix-session-api.ts` |
625
+ | `helix session send <id> --session <sid>` (internal) | `POST /api/sandbox/:id/input` `{sessionId, line}` | `commands/helix/send.ts` → `lib/sandbox-api.ts` |
626
+ | `helix session signal <ref>` | `POST SESSIONS/<ref>/signal` `{signal}` (default `SIGINT`) | `commands/helix/signal.ts` → `lib/helix-session-api.ts` |
627
+ | `helix session signal <id> --session <sid>` (internal) | `POST /api/sandbox/:id/signal` `{sessionId, signal}` | `commands/helix/signal.ts` → `lib/sandbox-api.ts` |
628
+ | `helix session close-input <ref>` | `POST SESSIONS/<ref>/close-input` | `commands/helix/reference-commands.ts` → `lib/helix-session-api.ts` |
629
+ | `helix session checkpoint <ref>` | `POST SESSIONS/<ref>/checkpoint` | `commands/helix/session-commands.ts` → `lib/helix-session-api.ts` |
630
+ | `helix session checkpoint <id> --session <sid>` (internal) | `POST /api/sandbox/:id/checkpoint` | `commands/helix/session-commands.ts` → `lib/sandbox-checkpoints.ts` |
631
+ | `helix session checkpoints <ref>` | `GET SESSIONS/<ref>/checkpoints` | `commands/helix/reference-commands.ts` → `lib/helix-session-api.ts` |
632
+ | `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` |
633
+ | `helix session start <sandbox-id>` (internal) | `POST /api/sandbox/:id/session` `{mode, args?, cwd?, environment?}` | `commands/helix/session-commands.ts` → `lib/sandbox-api.ts` |
634
+ | `helix models` | `GET /api/sandbox/helix/defaults` | `commands/helix/models.ts` → `lib/sandbox-api.ts` |
635
+ | `helix models default <ids…>`, `--clear` | `PUT /api/sandbox/helix/defaults` `{models}` (`--clear` sends `[]`) | `commands/helix/models.ts` → `lib/sandbox-api.ts` |
636
+ | `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` |
637
+ | `helix version` | `GET /api/sandbox/presets` | `commands/helix/doctor.ts` → `lib/sandbox-catalog.ts` |
638
+ | `helix update` | `GET /api/sandbox/presets` to name the pinned version, then exit 2 | `commands/helix/doctor.ts` |
476
639
 
477
640
  All source paths in this table are under `mutagent-cli/src/`.
478
641
 
479
- ### `mutagent agent` verbs
642
+ #### `mutagent agent` verbs
480
643
 
481
644
  | Verb | API call | CLI source |
482
645
  |---|---|---|
483
- | `agent check <agent.md>` | local, no API: compile and validate the folder | `commands/agent/index.ts:32-36` → `lib/agent/local.ts:44-47` |
484
- | `agent pack <agent.md> --output <archive>` | local, no API: write the package archive | `commands/agent/index.ts:37-43` → `lib/agent/local.ts:48-60` |
485
- | `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:44-55` → `lib/agent/local.ts:61-75` |
486
- | `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:56-66` → `lib/agent/service.ts:15-18` → `lib/agent/remote.ts:35-74` → `lib/agent/sdk.ts:64-67`, `:81-87` |
487
- | `agent activate <slug> --revision vN [--env] [--idempotency-key]` | `POST /api/helix-agent/agents/{slug}/activate` `{revision, environment?, idempotencyKey}` | `commands/agent/index.ts:67-78` → `lib/agent/remote.ts:105-118` → `lib/agent/sdk.ts:88-91` |
488
- | `agent list [--limit] [--cursor] [--include-archived]` | `GET /api/helix-agent/agents` | `commands/agent/index.ts:79-88` → `lib/agent/remote.ts:76-92` → `lib/agent/sdk.ts:68-71` |
489
- | `agent inspect <slug> [--env] [--limit] [--cursor]` | `GET /api/helix-agent/agents/{slug}` (revisions, slots, sessions; `--env` filters on the client) | `commands/agent/index.ts:89-102` → `lib/agent/remote.ts:94-103` → `lib/agent/sdk.ts:72-80` |
490
- | `agent inspect --operation <id>` | `GET /api/helix-agent/operations/{operationId}` | `lib/agent/remote.ts:95` → `lib/agent/sdk.ts:93` |
491
- | `agent retire <slug> [--env]` | `POST /api/helix-agent/agents/{slug}/retire` `{environment?}` | `commands/agent/index.ts:103-108` → `lib/agent/remote.ts:120-126` → `lib/agent/sdk.ts:92` |
492
-
493
- All source paths in this table are under `mutagent-cli/src/`. The route paths are the generated SDK's
494
- (`mutagent-sdk/src/funcs/helix-agent-deployments-*.ts`) and match the server routes in
495
- `mutagent/src/modules/helix-agent/deployment/routes.ts:69-173`.
496
-
497
- Running a deployed agent is not an `agent` verb: it is `mutagent helix agent @slug`, which uses the
498
- same launch route as every cloud run (row above).
646
+ | `agent check <agent.md>` | local, no API: compile and validate the folder | `commands/agent/index.ts` → `lib/agent/local.ts` |
647
+ | `agent pack <agent.md> --output <archive>` | local, no API: write the package archive | `commands/agent/index.ts` → `lib/agent/local.ts` |
648
+ | `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` |
649
+ | `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` |
650
+ | `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` |
651
+ | `agent list [--limit] [--cursor] [--include-archived]` | `GET /api/helix-agent/agents` | `commands/agent/index.ts` → `lib/agent/remote.ts` → `lib/agent/sdk.ts` |
652
+ | `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` |
653
+ | `agent inspect --operation <id>` | `GET /api/helix-agent/operations/{operationId}` | `lib/agent/remote.ts` → `lib/agent/sdk.ts` |
654
+ | `agent retire <slug> [--env]` | `POST /api/helix-agent/agents/{slug}/retire` `{environment?}` | `commands/agent/index.ts` → `lib/agent/remote.ts` → `lib/agent/sdk.ts` |
499
655
 
500
- ---
656
+ All source paths in this table are under `mutagent-cli/src/`. The route paths are
657
+ the generated SDK's (`mutagent-sdk/src/funcs/managed-agents-*.ts`) and match the
658
+ server routes in `mutagent/src/modules/helix-agent/deployment/routes.ts`.
659
+
660
+ Running a deployed agent is not an `agent` verb: it is `mutagent helix agent @slug`,
661
+ which uses the same launch route as every cloud run (row above).
501
662
 
502
- ## AI-First Usage
663
+ ### AI-first usage
503
664
 
504
- Every command supports `--json` for machine-readable output with `_directive`
505
- (next-step guidance for agents) and `_links` (dashboard/API URLs):
665
+ Platform commands support `--json` with `_directive` (next-step guidance for
666
+ agents) and `_links` (dashboard/API URLs). Cloud Helix runs stream native Helix
667
+ output.
506
668
 
507
669
  ```bash
508
- # Zero-config with env var
509
- export MUTAGENT_API_KEY="mt_live_xxxx"
670
+ export MUTAGENT_API_KEY="mg_live_xxxx" # Zero-config with env var
510
671
 
511
- # Discover the surface
512
- mutagent --help
672
+ mutagent --help # Discover the surface
513
673
  mutagent --version --json
514
674
 
515
- # JSON output
516
- mutagent workspaces list --json
675
+ mutagent workspaces list --json # JSON output
517
676
  mutagent providers list --models --json
518
677
  mutagent usage --json
519
678
 
520
- # Non-interactive mode
521
- mutagent init --non-interactive
522
-
523
- # Install the skill so agents can self-serve
524
- mutagent skills install
679
+ mutagent init --non-interactive # Non-interactive mode
680
+ mutagent skills install # Install the skill so agents can self-serve
525
681
  ```
526
682
 
527
- ### JSON Directive & Links
683
+ #### JSON Directive & Links
528
684
 
529
685
  `--json` responses may include:
530
686
 
531
687
  | Field | Meaning |
532
- |-------|---------|
688
+ |---|---|
533
689
  | `_directive.renderedCard` | Pre-formatted status card — agents **must** echo it verbatim in chat |
534
690
  | `_directive.instruction` | Self-contained next step for the agent |
535
691
  | `_directive.next` | Array of suggested follow-up commands |
536
692
  | `_links` | Dashboard / API URLs |
537
693
  | `_compat` | Compat metadata: `cliVersion`, `skillVersion`, `skillMinCliVersion` |
538
694
 
539
- ### Exit Codes
695
+ #### Exit codes
540
696
 
541
697
  | Code | Meaning |
542
- |------|---------|
698
+ |---|---|
543
699
  | `0` | Success |
544
700
  | `1` | General error |
545
701
  | `2` | Authentication required |
@@ -548,84 +704,18 @@ mutagent skills install
548
704
  | `6` | Rate limit exceeded |
549
705
  | `8` | Permission error |
550
706
 
551
- ---
552
-
553
- ## Configuration
554
-
555
- ### Environment Variables
556
-
557
- ```bash
558
- MUTAGENT_API_KEY=mt_live_xxxxxxxx
559
- MUTAGENT_ENDPOINT=https://api.mutagent.io
560
- MUTAGENT_APP_URL=https://app.mutagent.io
561
- ```
562
-
563
- ### RC Files
564
-
565
- `mutagent init` writes `.mutagentrc.json`. Example:
566
-
567
- ```json
568
- {
569
- "endpoint": "https://api.mutagent.io",
570
- "format": "table"
571
- }
572
- ```
573
-
574
- ### Persistent Defaults
575
-
576
- ```bash
577
- mutagent config set workspace <id> # Avoid passing workspace on every command
578
- mutagent config set org <id> # Required for org-scoped API keys
579
- ```
580
-
581
- ### Global Config
707
+ ### See also
582
708
 
583
- Credentials are stored in `~/.config/mutagent/credentials.json` (created by
584
- `mutagent login`).
585
-
586
- ---
587
-
588
- ## Development
589
-
590
- ### Prerequisites
591
-
592
- - [Bun](https://bun.sh) >= 1.0.0
593
- - Node.js >= 22.0.0 (fallback)
594
-
595
- ### Setup
596
-
597
- ```bash
598
- git clone https://github.com/mutagent/mutagent-cli.git
599
- cd mutagent-cli
600
- bun install
601
- ```
602
-
603
- ### Commands
604
-
605
- ```bash
606
- bun run dev # Run in development mode
607
- bun run build # Build
608
- bun run type-check # Type check
609
- bun run lint # Lint
610
- bun run lint:fix # Lint with auto-fix
611
- bun run test # Run all tests
612
- bun run verify # Full verification (lint + type-check + build)
613
- ```
614
-
615
- ---
616
-
617
- ## See Also
618
-
619
- - **[@mutagent/sdk](https://www.npmjs.com/package/@mutagent/sdk)** — TypeScript SDK for programmatic access
620
- - **[docs.mutagent.io](https://docs.mutagent.io)** — Full platform documentation
621
- - **[CLI Commands Reference](https://docs.mutagent.io/cli/commands)** — All commands with flags
622
- - **[mutagent.io](https://mutagent.io)** — Homepage
709
+ - [`@mutagent/sdk`](../mutagent-sdk/README.md) — TypeScript SDK for programmatic access
710
+ - [Backend API](../mutagent/README.md) — the server this CLI talks to
711
+ - [docs.mutagent.io](https://docs.mutagent.io) — full platform documentation
712
+ - [mutagent.io](https://mutagent.io) — homepage
623
713
 
624
714
  ---
625
715
 
626
716
  ## License
627
717
 
628
- This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.
718
+ Released under the [Apache License 2.0](./LICENSE).
629
719
 
630
720
  (c) 2026 MutagenT. All rights reserved.
631
721
 
@@ -634,9 +724,3 @@ This software is proprietary and confidential. Unauthorized copying, distributio
634
724
  <p align="center">
635
725
  <sub>Built with care by the MutagenT Team</sub>
636
726
  </p>
637
-
638
- <p align="center">
639
- <a href="https://twitter.com/mutagent">Twitter</a> •
640
- <a href="https://discord.gg/mutagent">Discord</a> •
641
- <a href="https://mutagent.io">Website</a>
642
- </p>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mutagent/cli",
3
- "version": "0.1.356",
3
+ "version": "0.1.357",
4
4
  "description": "Bun-native CLI for the MutagenT AI platform - auth, provider config, and lifecycle-tool installer for AI-native workflows",
5
5
  "type": "module",
6
6
  "bin": {