@mutagent/cli 0.2.59 → 0.2.61

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 +309 -619
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,712 +1,383 @@
1
- ![MutagenT](../assets/brand/mutagent-banner.svg)
2
-
3
- # MutagenT CLI
1
+ # Mutagent CLI
4
2
 
5
3
  <p align="center">
6
4
  <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>
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>
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>
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>
5
+ <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 22.18+"></a>
6
+ <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 1.1+"></a>
7
+ <a href="./LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue?style=for-the-badge" alt="License: Apache 2.0"></a>
11
8
  </p>
12
9
 
13
10
  <p align="center">
14
- <strong>Authenticate. Manage the platform. Run Helix locally and in the cloud.</strong>
11
+ <strong>Run Helix and your own agents in cloud sandboxes, from your terminal or your coding agent.</strong>
15
12
  </p>
16
13
 
17
- ---
18
-
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 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 (in Helix) and exits with an error.
27
-
28
- [Context](#context) · [Concepts](#concepts) · [Components](#components) · [Configuration](#configuration) · [Reference](#reference)
29
-
30
- ---
31
-
32
- ## Context
33
-
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
-
43
- ### Key features
44
-
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 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
53
-
54
- ---
55
-
56
- ## Concepts
57
-
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).
65
-
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"}}}%%
68
- flowchart TD
69
- INSTALL["npm i -g @mutagent/cli"] --> AUTH_CHOICE{How to authenticate?}
70
-
71
- AUTH_CHOICE -->|Interactive / browser OAuth| LOGIN["mutagent login"]
72
- AUTH_CHOICE -->|Force browser| LOGIN_B["mutagent login --browser"]
73
- AUTH_CHOICE -->|CI / env var| ENV_AUTH["export MUTAGENT_API_KEY=mg_live_...<br/>mutagent login --json"]
74
-
75
- LOGIN --> INIT["mutagent init<br/>(.mutagentrc.json)"]
76
- LOGIN_B --> INIT
77
- ENV_AUTH --> INIT
78
-
79
- INIT --> SETUP
80
-
81
- subgraph SETUP ["Project Setup & Discovery"]
82
- direction TB
83
-
84
- subgraph AUTH_CMDS ["Auth & Config"]
85
- AUTH_STATUS["mutagent auth status"]
86
- AUTH_LOGOUT["mutagent auth logout"]
87
- CONFIG_LIST["mutagent config list"]
88
- CONFIG_SET_WS["mutagent config set workspace <id>"]
89
- CONFIG_SET_ORG["mutagent config set org <id>"]
90
- end
91
-
92
- subgraph PLATFORM_CMDS ["Platform (read-only)"]
93
- WS_LIST["mutagent workspaces list"]
94
- WS_GET["mutagent workspaces get <id>"]
95
- USAGE["mutagent usage"]
96
- end
97
-
98
- subgraph PROVIDER_CMDS ["LLM providers (BYOK)"]
99
- PROV_LIST["mutagent providers list"]
100
- PROV_ADD["mutagent providers add"]
101
- PROV_MIRROR["mutagent providers mirror"]
102
- end
103
-
104
- subgraph AGENT_TOOLING ["Coding-Agent Tooling"]
105
- SKILLS["mutagent skills install"]
106
- HOOKS["mutagent hooks install"]
107
- end
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)"]
115
- end
116
-
117
- subgraph LIFECYCLE ["Helix & Feedback"]
118
- INSTALL_PKG["mutagent install helix"]
119
- FEEDBACK["mutagent feedback send"]
120
- end
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
136
- ```
137
-
138
- ---
139
-
140
- ## Components
141
-
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
157
- ```
158
-
159
- Entry point: `src/bin/cli.ts`, built to `dist/bin/cli.js` (the `mutagent` bin).
160
-
161
- ### Commands (package scripts)
162
-
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`).
177
-
178
- ### Prerequisites
179
-
180
- - [Bun](https://bun.sh) >= 1.1.0
181
- - Node.js >= 22.18 (fallback runtime; Bun is primary)
14
+ `mutagent` is the command-line client for the [Mutagent](https://mutagent.io) platform. With it you can:
182
15
 
183
- ### Setup
184
-
185
- ```bash
186
- git clone https://github.com/architech-printworks/mutagent-monorepo.git
187
- cd mutagent-monorepo
188
- bun install
189
- cd mutagent-cli
190
- ```
16
+ - sign in and choose a workspace;
17
+ - add your own LLM provider keys (BYOK);
18
+ - store the variables and secrets your agents' tools need;
19
+ - run Helix on a task in a cloud sandbox, and follow or steer the session;
20
+ - deploy and run managed agents (`agent.md` folders);
21
+ - connect GitHub and Slack, and set up triggers and routines that start runs;
22
+ - install the Helix binary on your own machine.
191
23
 
192
- ### Reference material
24
+ Every command supports `--json`, so a coding agent can drive the CLI as easily as a person can.
193
25
 
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
26
+ **Documentation:** [docs.mutagent.io/cli](https://docs.mutagent.io/cli)
197
27
 
198
28
  ---
199
29
 
200
- ## Configuration
201
-
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):
250
-
251
- ```json
252
- {
253
- "endpoint": "https://api.mutagent.io",
254
- "format": "table"
255
- }
256
- ```
257
-
258
- `mutagent config set workspace <id>` / `mutagent config set org <id>` add
259
- `defaultWorkspace` / `defaultOrganization` to the same file.
30
+ ## Contents
260
31
 
261
- ### Global config
262
-
263
- Credentials are stored in `~/.config/mutagent/credentials.json`, created by
264
- `mutagent login`. No ports: this package is a CLI, not a server.
32
+ - [Install](#install)
33
+ - [Quick start](#quick-start)
34
+ - [Concepts](#concepts)
35
+ - [Commands](#commands)
36
+ - [Scripts, CI and coding agents](#scripts-ci-and-coding-agents)
37
+ - [Configuration](#configuration)
38
+ - [Links](#links)
265
39
 
266
40
  ---
267
41
 
268
- ## Reference
269
-
270
- ### Installation
42
+ ## Install
271
43
 
272
44
  ```bash
273
- # Bun (recommended)
45
+ npm install -g @mutagent/cli
46
+ # or
274
47
  bun install -g @mutagent/cli
275
48
 
276
- # npm
277
- npm install -g @mutagent/cli
49
+ mutagent --version
278
50
  ```
279
51
 
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).
282
-
283
- ```bash
284
- mutagent --version # Verify installation
285
- ```
52
+ Requires Node.js 22.18 or later, or Bun 1.1 or later.
286
53
 
287
- ### Quick start
54
+ ## Quick start
288
55
 
289
56
  ```bash
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
312
- ```
313
-
314
- `mutagent login` is the canonical command; `mutagent auth login` is a back-compat
315
- alias, both identical.
57
+ # 1. Sign in: opens the browser (or set MUTAGENT_API_KEY, see below)
58
+ mutagent login
316
59
 
317
- ### Command reference
60
+ # 2. Add an LLM provider key, read from stdin so it stays out of your shell history
61
+ mutagent providers add --provider openai --name "My OpenAI" --api-key-stdin < key.txt
62
+ # or copy the keys from your local Helix login
63
+ mutagent providers mirror
318
64
 
319
- The active command surface: `login` · `auth` · `config` · `workspaces` · `providers` ·
320
- `usage` · `init` · `skills` · `hooks` · `install` · `sandbox` · `env` · `helix` ·
321
- `agent` · `trace` · `feedback`.
65
+ # 3. Create an Environment: the variables and secrets a sandbox gets
66
+ mutagent env set staging GREETING=hello --secrets-from-file .env.secrets
322
67
 
323
- Run `mutagent <command> --help` for the authoritative, current flag list — the CLI
324
- is the source of truth for flags.
325
-
326
- #### Global options
327
-
328
- | Option | Description |
329
- |---|---|
330
- | `--json` | Output results as JSON (for AI agents) |
331
- | `--api-key <key>` | Mutagent platform 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) |
336
-
337
- #### Authentication (`login` / `auth`)
68
+ # 4. Run Helix on a task in a cloud sandbox and print its answer
69
+ mutagent helix --env staging -p "check the deploy"
70
+ ```
338
71
 
339
- ```bash
340
- mutagent login # Browser OAuth (recommended)
341
- mutagent login --browser # Force browser flow
342
- mutagent login --json # Non-interactive (uses MUTAGENT_API_KEY)
72
+ To run Helix on your own machine instead, install the Helix binary with `mutagent install helix`.
343
73
 
344
- mutagent auth login # Back-compat alias for `mutagent login`
345
- mutagent auth status # Sign-in state, endpoint and active workspace
346
- mutagent auth logout # Clear stored credentials
347
- ```
74
+ ## Concepts
348
75
 
349
- #### Configuration (`config`)
76
+ - **Workspace**: the scope most commands act in. Your sign-in key works in every workspace you
77
+ belong to in its organization. `mutagent workspaces use <name>` selects one, and `--workspace`
78
+ overrides it for a single command.
79
+ - **LLM provider (BYOK)**: a model provider key (OpenAI, Anthropic, Google, ...) stored in the
80
+ workspace, encrypted. Helix uses it to call models in the cloud. Manage them with
81
+ `mutagent providers`.
82
+ - **Environment**: a named set of variables and secrets an agent's tools need, such as a GitHub
83
+ token or a database URL. Load one into a run with `--env <name>`. Values are write-only:
84
+ `mutagent env show` prints names and fingerprints, never a value. LLM provider keys do not
85
+ belong here.
86
+ - **Helix session**: a cloud run of Helix, addressed by a reference (`hs1_...`) that is printed
87
+ when the run starts. `mutagent helix session` lists sessions, attaches to them, sends input,
88
+ stops, checkpoints and restores them. A sandbox idle for 15 minutes is stopped, and an
89
+ interactive session in it is checkpointed first.
90
+ - **Managed agent**: a folder whose entry file is `agent.md` (YAML frontmatter, then the standing
91
+ prompt). `mutagent agent deploy` stores each change as a new revision. A slot is the agent in one
92
+ Environment (`--env`).
93
+ - **Sandbox provider and preset**: where a cloud run executes, and the named sandbox definition it
94
+ uses. Both are managed by the platform. You choose one per run with `--sandbox-provider` and
95
+ `--preset`.
96
+ - **Gateway**: connects GitHub and Slack, and runs Helix when an event or a schedule fires.
97
+
98
+ ## Commands
99
+
100
+ Run `mutagent --help`, or `mutagent <command> --help`, for the full and current flags of any
101
+ command. The [command reference](https://docs.mutagent.io/cli/commands) covers each group in
102
+ detail.
103
+
104
+ ### Sign in and workspaces
350
105
 
351
106
  ```bash
352
- mutagent config list # List all config values
353
- mutagent config get <key> # apiKey, endpoint, format, timeout, defaultWorkspace, defaultOrganization
354
- mutagent config set workspace <id> # Set default workspace
355
- mutagent config set org <id> # Set default organization
356
- ```
107
+ mutagent login # In a terminal, choose browser or API key
108
+ mutagent login --browser # Browser sign-in (sign in or sign up)
109
+ mutagent login --org <slug> # Sign in for another organization
110
+ MUTAGENT_API_KEY=mg_live_... mutagent login --json # Sign in with a key (CI)
357
111
 
358
- #### Project setup (`init`)
112
+ mutagent auth status # Sign-in state, endpoint and active workspace
113
+ mutagent auth logout # Clear the stored credentials
359
114
 
360
- ```bash
361
- mutagent init # Writes .mutagentrc.json + installs the CLI skill. Never prompts.
362
- ```
115
+ mutagent workspaces list # Your workspaces in the key's organization
116
+ mutagent workspaces use <name|id> # Every later command works in this workspace
117
+ mutagent workspaces current # The key's scope, organization and workspace
118
+ mutagent workspaces get <id> # One workspace
363
119
 
364
- #### Workspaces (`workspaces`, read-only)
120
+ mutagent config list # Every setting
121
+ mutagent config get endpoint # One setting
122
+ mutagent config set workspace <name|id> # Same as: mutagent workspaces use
123
+ mutagent config set org <id|slug> # Confirm the key's organization
365
124
 
366
- ```bash
367
- mutagent workspaces list # List all workspaces
368
- mutagent workspaces list --limit 20 --offset 0
369
- mutagent workspaces get <id> # Workspace details
125
+ mutagent usage # Count the workspace's LLM providers and your workspaces
370
126
  ```
371
127
 
372
- Create or change workspaces in the dashboard (https://app.mutagent.io).
128
+ `mutagent auth login` is the same command as `mutagent login`. Create or change workspaces in the
129
+ dashboard at [app.mutagent.io](https://app.mutagent.io).
373
130
 
374
- #### LLM providers (`providers`)
131
+ ### LLM providers (`providers`)
375
132
 
376
133
  ```bash
377
- mutagent providers mirror # Copy API keys from your local Helix login store
378
- mutagent providers list # List configured LLM providers
379
- mutagent providers list --models # Show available models per LLM provider
380
- mutagent providers get <id> # LLM provider details
381
- mutagent providers test <id> # Test LLM provider connectivity
382
-
383
- # Manage keys
384
- mutagent providers add # Add an LLM provider (--provider, --name, --api-key-stdin or --api-key, --base-url, --set-default)
385
- mutagent providers update <id> --name "New name" --active true
134
+ mutagent providers mirror # Copy the keys from your local Helix login (shows the plan, asks first)
135
+ mutagent providers list # The workspace's LLM providers
136
+ mutagent providers list --models # Catalogue models per LLM provider type
137
+ mutagent providers get <id>
138
+ mutagent providers test <id> # Test the saved key
139
+ mutagent providers add --provider anthropic --name "Anthropic" --api-key-stdin < key.txt
140
+ mutagent providers update <id> --name "New name"
386
141
  mutagent providers delete <id> --force
387
142
  ```
388
143
 
389
- LLM provider types: `openai`, `anthropic`, `google`, `moonshot`, `glm`, `deepseek`,
390
- `xai`, `azure`, `vertex`, `bedrock`, `custom`.
144
+ LLM provider types: `openai`, `anthropic`, `google`, `moonshot`, `glm`, `zai-coding-plan`,
145
+ `deepseek`, `xai`, `openrouter`, `azure`, `vertex`, `bedrock`, `custom`. Keys are stored encrypted
146
+ and never returned. `mutagent providers add --help` lists the extra flags for Azure, Vertex,
147
+ Bedrock and custom endpoints.
391
148
 
392
- #### Workspace Environments (`env`)
149
+ ### Environments (`env`)
393
150
 
394
151
  ```bash
395
- mutagent env list # List the workspace's Environments
396
- mutagent env set demo GREETING=hello --secret GITHUB_TOKEN=ghp_…
152
+ mutagent env list
153
+ mutagent env set demo GREETING=hello --secret GITHUB_TOKEN=ghp_...
397
154
  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
155
+ mutagent env show demo # Entry names and fingerprints, never a value
399
156
  mutagent env unset demo GREETING
400
157
  mutagent env delete demo --force
401
- mutagent helix --env demo -p "check the deploy" # Load it into a Helix cloud run
402
158
  ```
403
159
 
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>`).
160
+ `set` creates the Environment or merges into it. `--replace --force` overwrites it and removes
161
+ every entry you do not name. A variable named like an LLM provider key (`ANTHROPIC_API_KEY`, ...)
162
+ is refused unless you pass `--allow-provider-key`. Environment names use letters, digits, `.`, `_`
163
+ and `-` (up to 64 characters). Variable names use `A-Z`, `0-9` and `_`, and cannot start with a
164
+ digit. An Environment holds up to 64 KiB.
412
165
 
413
- #### Usage (`usage`)
166
+ ### Run Helix in the cloud (`helix`)
414
167
 
415
168
  ```bash
416
- mutagent usage # Account usage + LLM provider status
417
- mutagent usage --json # Machine-readable
169
+ mutagent helix -p "plan the refactor" # Run to completion and print the final answer
170
+ mutagent helix --mode json "run the tests" # Stream events as JSON lines
171
+ mutagent helix --mode rpc # A steerable session: JSON commands on stdin
172
+ mutagent helix --prime --mode rpc # The lean Prime agent instead of the full orchestrator
173
+ mutagent helix --env staging -p "check the deploy"
174
+ mutagent helix --repository acme/api --branch feat/login --mode rpc
418
175
  ```
419
176
 
420
- #### Skills & hooks (Claude Code)
177
+ | Run option | What it does |
178
+ |---|---|
179
+ | `-p "<task>"` | Run the task to completion and print the final answer |
180
+ | `--mode json "<task>"` | Stream events as JSON lines |
181
+ | `--mode rpc`, `--rpc` | Read JSON commands on stdin, write events on stdout |
182
+ | `--prime` | Run the lean Prime agent instead of the full orchestrator |
183
+ | `--model <provider/model>` | Model to use (default: the workspace default model) |
184
+ | `--env <name>` | Workspace Environment to load |
185
+ | `--preset <name>` | Sandbox preset (default: the server's Helix preset) |
186
+ | `--sandbox-provider <name>` | Run on this sandbox provider |
187
+ | `--cwd <path>` | Working directory in the sandbox |
188
+ | `--repository <owner/name>` | Run in a checkout of this GitHub repository (needs the workspace's GitHub connection) |
189
+ | `--branch <name>` | Branch of `--repository` to check out |
190
+
191
+ There is no terminal chat UI: choose `-p`, `--mode json` or `--mode rpc`. Each run prints its
192
+ session reference (`hs1_...`) on stderr. Ctrl-C stops the session.
421
193
 
422
194
  ```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
195
+ # Your own agent definition
196
+ mutagent helix agent "You are a test reviewer." -p "review the diff"
197
+ mutagent helix agent --file reviewer.md --mode json "run the suite"
198
+
199
+ # Sessions
200
+ mutagent helix session list
201
+ mutagent helix session attach <reference> # Watch it (--since <n> replays)
202
+ mutagent helix session send <reference> "and now the tests"
203
+ mutagent helix session send <reference> --type steer "stop and re-read the spec"
204
+ mutagent helix session signal <reference> --force # Stop it; the sandbox stays up
205
+ mutagent helix session close-input <reference>
206
+ mutagent helix session checkpoint <reference>
207
+ mutagent helix session checkpoints <reference>
208
+ mutagent helix session restore <reference> # Continue in a rebuilt sandbox
209
+
210
+ # Models
211
+ mutagent helix models # Models Helix can use, and the default
212
+ mutagent helix models default <provider/model> # Set the workspace default model
213
+
214
+ # Diagnostics
215
+ mutagent helix version # This CLI's version and the cloud Helix version
216
+ mutagent helix doctor # Helix's own diagnostics in a temporary sandbox
217
+ mutagent helix smoke # Helix's smoke test in a temporary sandbox
218
+
219
+ # Sandbox providers and presets a run can name
220
+ mutagent sandbox providers
221
+ mutagent sandbox presets
427
222
  ```
428
223
 
429
- #### Managed agents (`agent`, `helix agent @slug`)
224
+ Only an interactive session (`--mode rpc`) accepts `session send`. A send to a session whose
225
+ sandbox was stopped for idling wakes it from its last checkpoint.
430
226
 
431
- A managed agent is a folder whose entry file is `agent.md`: YAML frontmatter,
432
- then the standing prompt. The base fields (`name`, `description`, `model`,
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
436
- [tests/fixtures/agent-deployment](tests/fixtures/agent-deployment).
227
+ ### Managed agents (`agent`)
437
228
 
438
229
  ```bash
439
- mutagent agent check ./invoice/agent.md
440
- mutagent agent pack ./invoice/agent.md --output ./invoice.tgz
441
- mutagent agent run ./invoice/agent.md "Price three widget units."
442
- mutagent agent deploy ./invoice/agent.md --env prod
230
+ mutagent agent check invoice/agent.md # Compile and validate; nothing leaves the machine
231
+ mutagent agent pack invoice/agent.md --output invoice.tgz
232
+ mutagent agent run invoice/agent.md "Price three widget units." # Local, with the local Helix binary
233
+ mutagent agent deploy invoice/agent.md --env prod
443
234
  mutagent helix agent @invoice-pricing --env prod -p "Price three widget units."
444
- mutagent agent inspect invoice-pricing --env prod
445
- mutagent agent activate invoice-pricing --revision v2 --env prod
446
- mutagent agent retire invoice-pricing --env prod
447
235
  mutagent agent list
236
+ mutagent agent inspect invoice-pricing --env prod
237
+ mutagent agent activate invoice-pricing --revision v2 --env prod # An older revision is a rollback
238
+ mutagent agent retire invoice-pricing --env prod --force
239
+ mutagent agent spec diff invoice-pricing agentspec.yaml
240
+ mutagent agent activity invoice-pricing
241
+ mutagent agent versions invoice-pricing
448
242
  ```
449
243
 
450
- - `name` is the slug. `model` is `provider/model`, as `mutagent helix models`
451
- lists it; deploy and activate refuse a model outside the workspace model list.
452
- - Each deploy of new content is the next revision (`v1`, `v2`, ...); unchanged
453
- content reuses its revision. A slot is the agent in one Environment: `--env`
454
- names it, and no `--env` is the default slot. `--no-activate` stores the
455
- revision without moving the slot.
456
- - `mutagent helix agent @slug[:vN|:latest] [--env X] (-p "<task>" | --rpc)` runs
457
- it in the cloud. The receipt is one JSON line on stderr; its reference is what
458
- `mutagent helix session` commands take.
459
- - `agent run` runs a local `agent.md` on this machine with the local Helix binary
460
- (`mutagent install helix` puts one at `~/.mutagent/bin/helix`; `MUTAGENT_HELIX_BIN`
461
- selects another) and creates nothing in the workspace.
462
- - Compilation requires Bun 1.3.14 on `PATH` or `MUTAGENT_BUN_BIN`.
463
-
464
- #### Helix installer (`install`)
465
-
466
- ```bash
467
- mutagent install helix # latest channel
468
- mutagent install helix --channel candidate # candidate channel
469
- mutagent install helix --json # binaryPath, version, sha256, onPath, pathLine
470
- ```
471
-
472
- `mutagent install helix` does what `curl -fsSL https://install.mutagent.io/helix | bash`
473
- does: it downloads `helix-<os>-<arch>` (macOS or Linux, x64 or arm64) from
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. (The PATH step is
478
- where the two differ: the curl installer also symlinks `helix` into `~/.local/bin` or
479
- `~/bin` when one of them is already on `PATH`; this command does not.) When you are
480
- signed in, the CLI also records the install activation, best-effort; `--json`
481
- reports it as `telemetry` (`sent`, `skipped` or `failed`).
244
+ The `agent.md` frontmatter fields `name`, `description`, `model`, `thinking`, `tools`,
245
+ `disallowed_tools` and `skills` are a local brief. Deployment settings live in one optional
246
+ `harness:` block (tools, skills, files, bindings, runtime). `name` is the slug, and `model` is
247
+ `provider/model` as `mutagent helix models` lists it.
482
248
 
483
- `diagnostics` and `evaluator` are not install targets: both skills ship inside
484
- helix — passing either name fails with `INVALID_ARGUMENTS` naming `helix` instead.
249
+ Each deploy of new content is the next revision (`v1`, `v2`, ...). `--no-activate` stores it
250
+ without moving the slot. `@slug:vN` pins a revision and `@slug:latest` runs the newest one.
485
251
 
486
- See the [Configuration](#configuration) table above for `MUTAGENT_HELIX_CHANNEL`,
487
- `MUTAGENT_INSTALL_HOST` and `MUTAGENT_INSTALL_DIR`.
252
+ Compiling needs Bun 1.4.2 on `PATH` (or `MUTAGENT_BUN_BIN`). `agent run` needs a local Helix binary
253
+ (`mutagent install helix`).
488
254
 
489
- #### Sandbox management (`sandbox`, internal)
490
-
491
- Everyday use goes through `mutagent helix`, which spawns a sandbox implicitly.
492
- `mutagent sandbox` manages one directly — useful for scripted or long-lived work:
255
+ ### GitHub, Slack, triggers and routines (`gateway`)
493
256
 
494
257
  ```bash
495
- mutagent sandbox presets # Presets `mutagent helix --preset` can name
496
- mutagent sandbox providers # Providers `mutagent helix --sandbox-provider` can name
497
- mutagent sandbox preflight --image alpine:3.20 # Would this definition run?
498
- mutagent sandbox spawn --image alpine:3.20 --detach
499
- mutagent sandbox list
500
- mutagent sandbox status sbx_1
501
- mutagent sandbox exec --sandbox sbx_1 -- bun test
502
- mutagent sandbox attach sbx_1 --since 412
503
- mutagent sandbox traces sbx_1 # Spans recorded for a sandbox
504
- mutagent sandbox delete sbx_1 --force
258
+ mutagent gateway # What's connected, what's missing, the next command
259
+ mutagent gateway doctor # End-to-end check, with fixes
260
+ mutagent gateway connect github # Prints a URL to open (--wait polls until done)
261
+ mutagent gateway connect slack
262
+ mutagent gateway repos --linked
263
+ mutagent gateway repos link acme/api
264
+
265
+ mutagent gateway triggers create --on <kind> --repo acme/api --instruction "triage the new issue"
266
+ mutagent gateway routines create --every "weekdays 09:00" --tz Europe/Berlin --repo acme/api \
267
+ --instruction "summarise yesterday's failures"
268
+
269
+ mutagent gateway test-run --repo acme/api --wait # Start a real run to prove the path works
270
+ mutagent gateway runs --since 24h
271
+ mutagent gateway runs logs <runId> --follow
505
272
  ```
506
273
 
507
- `exec` without `--sandbox` runs one command in a fresh, one-shot sandbox and
508
- removes it; `spawn` leaves a sandbox running for `attach`/`exec --sandbox`. A
509
- sandbox idle 15 minutes is stopped (an interactive Helix session in it is
510
- checkpointed first); `mutagent helix session restore <reference>` rebuilds it.
511
- Requires a workspace (`mutagent config set workspace <id>`).
274
+ Routines need `--tz`. Destructive verbs (`disconnect`, `repos unlink`, `triggers delete`,
275
+ `routines delete`, `runs cancel`) need `--force`. See `mutagent gateway --help` for every verb.
512
276
 
513
- #### Feedback (`feedback`)
277
+ ### Reports, findings, triage and inbox
514
278
 
515
279
  ```bash
516
- mutagent feedback send "describe what went wrong" --category cli
517
- mutagent feedback send "eval gate unclear" --category stage:evaluate
518
- mutagent feedback send "the CLI crashed on init" \
519
- --category cli --session <session-id> --attach-transcript
520
- ```
521
-
522
- | Flag | Description |
523
- |---|---|
524
- | `<feedback>` | Feedback body / content (required, ≤10000 chars) |
525
- | `--title <string>` | Optional 5–8 word summary of the session timeline |
526
- | `--category <value>` | `cli` (default) · `helix` · `stage:<spec\|build\|evaluate\|diagnose\|optimize>` |
527
- | `--session <id>` | Link feedback to a session id (server `sessionId`) |
528
- | `--attach-transcript [path]` | Attach the coding-agent session JSONL (bare = auto-detect newest) |
529
-
530
- `--attach-transcript` uploads the full session JSONL (source code, absolute
531
- paths, repo names, internal hostnames) — use it only when explicitly asked to.
532
-
533
- ### Command surface
534
-
535
- The `mutagent helix` and `mutagent agent` trees and their API routes. The command
536
- definitions in [src/commands](src/commands/) are the source of truth.
537
-
538
- ```mermaid
539
- %%{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"}}}%%
540
- flowchart LR
541
- ROOT["mutagent"] --> HX["helix"]
542
- ROOT --> AG["agent"]
543
-
544
- HX --> HXRUN["helix -p or --mode json or --mode rpc<br/>classic arm, --prime selects the prime arm"]
545
- HX --> HXAGENT["helix agent"]
546
- HX --> HXSESSION["helix session"]
547
- HX --> HXMODELS["helix models"]
548
- HX --> HXDOCTOR["helix doctor"]
549
- HX --> HXSMOKE["helix smoke"]
550
- HX --> HXVERSION["helix version"]
551
- HX --> HXUPDATE["helix update<br/>always refused"]
552
-
553
- HXAGENT --> HXAGENTDEF["definition: positional, --prompt, --file, --name"]
554
- HXAGENT --> HXAGENTSLUG["@slug, @slug:vN, @slug:latest<br/>managed agent"]
555
-
556
- HXSESSION --> SLS["list"]
557
- HXSESSION --> SATTACH["attach"]
558
- HXSESSION --> SSEND["send"]
559
- HXSESSION --> SSIGNAL["signal"]
560
- HXSESSION --> SCLOSE["close-input"]
561
- HXSESSION --> SCHECKPOINT["checkpoint"]
562
- HXSESSION --> SCHECKPOINTS["checkpoints"]
563
- HXSESSION --> SRESTORE["restore"]
564
- HXSESSION --> SSTART["start<br/>internal, sandbox id"]
565
-
566
- HXMODELS --> MDEFAULT["default"]
567
-
568
- AG --> ACHECK["check<br/>local"]
569
- AG --> APACK["pack<br/>local"]
570
- AG --> ARUN["run<br/>local Helix binary"]
571
- AG --> ADEPLOY["deploy"]
572
- AG --> AACTIVATE["activate"]
573
- AG --> ALIST["list"]
574
- AG --> AINSPECT["inspect"]
575
- AG --> ARETIRE["retire"]
576
-
577
- classDef default fill:#161b22,stroke:#444c56,color:#e6edf3
578
- classDef surface fill:#1a3a5c,stroke:#4a90e2,color:#fff
579
- classDef runtime fill:#2d4a2d,stroke:#4a9e4a,color:#fff
580
- classDef tool fill:#2a1a4a,stroke:#bc8cff,color:#fff
581
- classDef data fill:#4a3a2d,stroke:#cc9944,color:#fff
582
- classDef external fill:#3a3a4a,stroke:#888,color:#e6edf3
583
- class ROOT,HX,AG surface
584
- class HXRUN,HXAGENT,HXSESSION,HXAGENTDEF,HXAGENTSLUG,ARUN,ADEPLOY,AACTIVATE runtime
585
- class HXMODELS,HXDOCTOR,HXSMOKE,HXVERSION,MDEFAULT,ACHECK,APACK tool
586
- class SLS,SATTACH,SSEND,SSIGNAL,SCLOSE,SCHECKPOINT,SCHECKPOINTS,SRESTORE,SSTART,ALIST,AINSPECT,ARETIRE data
587
- class HXUPDATE external
588
- ```
280
+ mutagent reports push <run-dir> --kind evaluator # Upload a run report Helix published
281
+ mutagent reports list
282
+ mutagent reports show <id> --html report.html
283
+ mutagent reports review <id>
589
284
 
590
- Registration: `mutagent-cli/src/bin/cli.ts` registers `helix` and `agent`;
591
- `mutagent-cli/src/commands/helix/index.ts` attaches `agent`, `session`, `models`,
592
- `doctor`, `smoke`, `version` and `update`; `mutagent-cli/src/commands/helix/session-commands.ts`
593
- attaches the session verbs; `mutagent-cli/src/commands/agent/index.ts` declares the
594
- `agent` verbs.
285
+ mutagent findings list --status open
286
+ mutagent findings set-status <id> resolved
595
287
 
596
- #### Credentials
288
+ mutagent triage file --subject <id> --title "<one line>" --body @notes.md # Previews; --yes sends
289
+ mutagent triage list
290
+ mutagent triage set-status <id> resolved
597
291
 
598
- The two trees authenticate differently.
292
+ mutagent inbox list
293
+ mutagent inbox read-all
294
+ ```
599
295
 
600
- - **`mutagent helix …`** goes through `requestJson` (`mutagent-cli/src/lib/sandbox-api.ts`).
601
- Each request carries `Authorization: Bearer <operator token>` and `x-workspace-id`.
602
- The operator token is minted from the platform API key by `POST /api/sandbox/token`
603
- (`mutagent-cli/src/lib/sandbox-token.ts`) and cached; a 401 drops the cached
604
- token and mints once more.
605
- - **`mutagent agent …`** (the remote verbs) goes through the generated SDK client
606
- `sdk.managedAgents` with the platform API key and an `x-workspace-id` header, and
607
- no token exchange (`mutagent-cli/src/lib/agent/sdk.ts`). The server mounts these
608
- routes under `/api/helix-agent` (`mutagent/src/modules/helix-agent/deployment/module.ts`).
296
+ ### Trace sources (`integrations`)
609
297
 
610
- #### `mutagent helix` verbs
298
+ ```bash
299
+ mutagent integrations sources list
300
+ pass show langfuse/sk | mutagent integrations sources add langfuse --name prod --public-key pk-lf-... --secret-stdin
301
+ mutagent integrations sources test <id>
302
+ mutagent integrations sources pull <id> --since 2026-10-01T00:00:00Z
303
+ ```
611
304
 
612
- `<ref>` is a session reference (`hs1_…`). `SESSIONS` is `/api/sandbox/helix/sessions`
613
- (`mutagent-cli/src/lib/helix-session-api.ts`).
305
+ Connects Langfuse or OpenObserve trace sources and pulls their traces. Credentials are write-only.
614
306
 
615
- | Verb | API call | CLI source |
616
- |---|---|---|
617
- | `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` |
618
- | `helix … --sandbox <id>` (internal) | `POST /api/sandbox/:id/session`, then the attach loop | `commands/helix/run-cloud.ts` → `lib/sandbox-api.ts` |
619
- | 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` |
620
- | `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` |
621
- | `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` |
622
- | `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` |
623
- | `helix session list` | `GET SESSIONS[?limit=&cursor=]` | `commands/helix/session-commands.ts` → `lib/helix-session-api.ts` |
624
- | `helix session list <sandbox-id>` (internal) | `GET /api/sandbox/:id/sessions` | `commands/helix/session-commands.ts` → `lib/sandbox-api.ts` |
625
- | `helix session attach <ref>` | `GET SESSIONS/<ref>/stream[?since=]` | `commands/helix/session-commands.ts` → `lib/helix-session-api.ts` |
626
- | `helix session send <ref>` | `POST SESSIONS/<ref>/input` `{line}` | `commands/helix/send.ts` → `lib/helix-session-api.ts` |
627
- | `helix session send <id> --session <sid>` (internal) | `POST /api/sandbox/:id/input` `{sessionId, line}` | `commands/helix/send.ts` → `lib/sandbox-api.ts` |
628
- | `helix session signal <ref>` | `POST SESSIONS/<ref>/signal` `{signal}` (default `SIGINT`) | `commands/helix/signal.ts` → `lib/helix-session-api.ts` |
629
- | `helix session signal <id> --session <sid>` (internal) | `POST /api/sandbox/:id/signal` `{sessionId, signal}` | `commands/helix/signal.ts` → `lib/sandbox-api.ts` |
630
- | `helix session close-input <ref>` | `POST SESSIONS/<ref>/close-input` | `commands/helix/reference-commands.ts` → `lib/helix-session-api.ts` |
631
- | `helix session checkpoint <ref>` | `POST SESSIONS/<ref>/checkpoint` | `commands/helix/session-commands.ts` → `lib/helix-session-api.ts` |
632
- | `helix session checkpoint <id> --session <sid>` (internal) | `POST /api/sandbox/:id/checkpoint` | `commands/helix/session-commands.ts` → `lib/sandbox-checkpoints.ts` |
633
- | `helix session checkpoints <ref>` | `GET SESSIONS/<ref>/checkpoints` | `commands/helix/reference-commands.ts` → `lib/helix-session-api.ts` |
634
- | `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` |
635
- | `helix session start <sandbox-id>` (internal) | `POST /api/sandbox/:id/session` `{mode, args?, cwd?, environment?}` | `commands/helix/session-commands.ts` → `lib/sandbox-api.ts` |
636
- | `helix models` | `GET /api/sandbox/helix/defaults` | `commands/helix/models.ts` → `lib/sandbox-api.ts` |
637
- | `helix models default <ids…>`, `--clear` | `PUT /api/sandbox/helix/defaults` `{models}` (`--clear` sends `[]`) | `commands/helix/models.ts` → `lib/sandbox-api.ts` |
638
- | `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` |
639
- | `helix version` | `GET /api/sandbox/presets` | `commands/helix/doctor.ts` → `lib/sandbox-catalog.ts` |
640
- | `helix update` | `GET /api/sandbox/presets` to name the pinned version, then exit 1 (`NOT_SUPPORTED`) | `commands/helix/doctor.ts` |
641
-
642
- All source paths in this table are under `mutagent-cli/src/`.
643
-
644
- #### `mutagent agent` verbs
645
-
646
- | Verb | API call | CLI source |
647
- |---|---|---|
648
- | `agent check <agent.md>` | local, no API: compile and validate the folder | `commands/agent/index.ts` → `lib/agent/local.ts` |
649
- | `agent pack <agent.md> --output <archive>` | local, no API: write the package archive | `commands/agent/index.ts` → `lib/agent/local.ts` |
650
- | `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` |
651
- | `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` |
652
- | `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` |
653
- | `agent list [--limit] [--cursor] [--include-archived]` | `GET /api/helix-agent/agents` | `commands/agent/index.ts` → `lib/agent/remote.ts` → `lib/agent/sdk.ts` |
654
- | `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` |
655
- | `agent inspect --operation <id>` | `GET /api/helix-agent/operations/{operationId}` | `lib/agent/remote.ts` → `lib/agent/sdk.ts` |
656
- | `agent retire <slug> [--env]` | `POST /api/helix-agent/agents/{slug}/retire` `{environment?}` | `commands/agent/index.ts` → `lib/agent/remote.ts` → `lib/agent/sdk.ts` |
307
+ ### Setup: Helix binary, project, skill and hooks
657
308
 
658
- All source paths in this table are under `mutagent-cli/src/`. The route paths are
659
- the generated SDK's (`mutagent-sdk/src/funcs/managed-agents-*.ts`) and match the
660
- server routes in `mutagent/src/modules/helix-agent/deployment/routes.ts`.
309
+ ```bash
310
+ mutagent install helix # The Helix binary, into ~/.mutagent/bin (no sign-in needed)
311
+ mutagent install helix --channel candidate
661
312
 
662
- Running a deployed agent is not an `agent` verb: it is `mutagent helix agent @slug`,
663
- which uses the same launch route as every cloud run (row above).
313
+ mutagent init # Write .mutagentrc.json and install the CLI skill
314
+ mutagent skills install # .claude/skills/mutagent-cli/SKILL.md for Claude Code
315
+ mutagent hooks install # Claude Code session telemetry (.claude/settings.local.json)
316
+ mutagent hooks import session.jsonl --dry-run # Upload Helix session transcripts as traces
317
+ ```
664
318
 
665
- ### AI-first usage
319
+ `mutagent install helix` downloads the Helix binary for macOS or Linux (x64 or arm64) from
320
+ `install.mutagent.io`, checks it against the published checksums, and writes
321
+ `~/.mutagent/bin/helix`. It never edits your shell rc files: when the directory is not on `PATH`,
322
+ it prints the line to add. When you are signed in, it also records the install; that step never
323
+ fails the install.
666
324
 
667
- Platform commands support `--json` with `_directive` (next-step guidance for
668
- agents) and `_links` (dashboard/API URLs). Cloud Helix runs stream native Helix
669
- output.
325
+ ### Feedback
670
326
 
671
327
  ```bash
672
- export MUTAGENT_API_KEY="mg_live_xxxx" # Zero-config with env var
328
+ mutagent feedback send "describe what went wrong" --category cli
329
+ mutagent feedback send "eval gate was confusing" --category stage:evaluate
330
+ ```
673
331
 
674
- mutagent --help # Discover the surface
675
- mutagent --version --json
332
+ Categories: `cli` (default), `helix`, `stage:<spec|build|evaluate|diagnose|optimize>`.
333
+ `--attach-transcript` uploads your coding-agent session transcript, which contains source code,
334
+ paths and the context of your prompts. Use it only when you mean to share all of that.
676
335
 
677
- mutagent workspaces list --json # JSON output
678
- mutagent providers list --models --json
679
- mutagent usage --json
336
+ ### Global options
680
337
 
681
- mutagent init --non-interactive # Non-interactive mode
682
- mutagent skills install # Install the skill so agents can self-serve
683
- ```
338
+ | Option | What it does |
339
+ |---|---|
340
+ | `--json` | Print structured JSON instead of tables |
341
+ | `--api-key <key>` | Use this Mutagent API key instead of the stored one |
342
+ | `--endpoint <url>` | Use this Mutagent server instead of the configured one |
343
+ | `--workspace <name\|id>` | Run this one command in another workspace |
344
+ | `--org <id\|slug>` | Check that the key belongs to this organization; a mismatch exits 1 and sends nothing |
345
+ | `--non-interactive` | Never prompt (also when `CI=true` or stdin is not a terminal) |
346
+ | `-h, --help` | Help for any command |
347
+ | `-v, --version` | CLI version (only before a subcommand) |
684
348
 
685
- #### JSON Directive & Links
349
+ With `mutagent helix`, put `--api-key` and `--endpoint` before `helix`
350
+ (`mutagent --api-key <key> helix -p "<task>"`). After `helix` they are refused, so a model key
351
+ cannot be sent as your Mutagent key.
686
352
 
687
- `--json` responses may include:
353
+ ## Scripts, CI and coding agents
688
354
 
689
- | Field | Meaning |
690
- |---|---|
691
- | `_directive.renderedCard` | Pre-formatted status card — agents **must** echo it verbatim in chat |
692
- | `_directive.instruction` | Self-contained next step for the agent |
693
- | `_directive.next` | Array of suggested follow-up commands |
694
- | `_links` | Dashboard / API URLs |
695
- | `_compat` | Compat metadata: `cliVersion`, `skillVersion`, `skillMinCliVersion` |
355
+ ```bash
356
+ export MUTAGENT_API_KEY="mg_live_..." # Sign in without a browser
357
+ mutagent login --json
358
+ mutagent workspaces list --json
359
+ mutagent providers list --json
360
+ ```
696
361
 
697
- #### Exit codes and failures
362
+ - **Coding agents:** run `mutagent skills install` first. It installs a skill that teaches the agent
363
+ the CLI's workflows. To help a person sign in, run `mutagent login --browser --json`, show them the
364
+ printed URL, and wait (the CLI polls for up to 5 minutes).
365
+ - **JSON:** pass `--json` to every command except a `mutagent helix` launch, whose output is Helix's
366
+ own. A response may carry `_directive` (a status card and the next step for an agent), `_links`
367
+ (dashboard and API URLs) and `_compat` (CLI and skill versions).
368
+ - **Destructive commands** (delete, retire, signal, cancel, ...) need `-f/--force` in every mode.
369
+ Without it they refuse with `CONFIRMATION_REQUIRED` and send nothing. They never prompt.
698
370
 
699
- One table for every command (`EXIT_CODES` in `src/lib/errors.ts`):
371
+ ### Exit codes
700
372
 
701
373
  | Code | Meaning |
702
374
  |---|---|
703
375
  | `0` | Success |
704
- | `1` | Failure, usage errors included (unknown command or option, a missing argument) |
705
- | `2` | The API key expired or is invalid (a key from another service included) |
376
+ | `1` | Failure, usage errors included |
377
+ | `2` | The API key expired or is invalid |
706
378
  | `3` | Not signed in, or no workspace selected |
707
379
 
708
- Exit 0 means success and nothing else: under `--json`, `success: true` if and only if the
709
- exit code is 0. A failure under `--json` is one object on stdout:
380
+ Under `--json`, `success: true` if and only if the exit code is 0. A failure is one object on stdout:
710
381
 
711
382
  ```json
712
383
  {
@@ -717,32 +388,51 @@ exit code is 0. A failure under `--json` is one object on stdout:
717
388
  "_agentGuidance": {
718
389
  "helpCommand": "mutagent env ls --help",
719
390
  "fix": ["mutagent env ls --help"],
720
- "notes": [],
721
- "escalate": "Present only when a person has to act"
391
+ "notes": []
722
392
  }
723
393
  }
724
394
  ```
725
395
 
726
- In a terminal the same failure is `Error: …` on stderr, with the fix. Commands that forward
727
- a remote process (`sandbox exec`, a Helix run) exit with that process's own code.
396
+ `_agentGuidance.escalate` is present only when a person has to act. In a terminal the same failure
397
+ is `Error: ...` on stderr, with the fix. A Helix run exits with the session's own exit code.
728
398
 
729
- ### See also
399
+ ## Configuration
730
400
 
731
- - [`@mutagent/sdk`](../mutagent-sdk/README.md) — TypeScript SDK for programmatic access
732
- - [Backend API](../mutagent/README.md) — the server this CLI talks to
733
- - [docs.mutagent.io](https://docs.mutagent.io) — full platform documentation
734
- - [mutagent.io](https://mutagent.io) — homepage
401
+ ### Environment variables
735
402
 
736
- ---
403
+ | Variable | Default | What it does |
404
+ |---|---|---|
405
+ | `MUTAGENT_API_KEY` | none | Mutagent API key; sign in without a browser |
406
+ | `MUTAGENT_ENDPOINT` | `https://api.mutagent.io` | Mutagent server |
407
+ | `MUTAGENT_WORKSPACE_ID` | the selected workspace | Workspace for every command (`--workspace` wins) |
408
+ | `MUTAGENT_NON_INTERACTIVE` | unset | `true` disables every prompt |
409
+ | `CI` | unset | `true` also disables every prompt |
410
+ | `NO_COLOR` | unset | Any value disables color |
411
+ | `MUTAGENT_NO_BANNER` | unset | `1` hides the banner |
412
+ | `MUTAGENT_DEBUG` | unset | `1`, `true` or `yes` writes redacted request logs to stderr |
413
+ | `MUTAGENT_HELIX_CHANNEL` | `latest` | Channel for `mutagent install helix` (`latest` or `candidate`; `--channel` wins) |
414
+ | `MUTAGENT_INSTALL_DIR` | `~/.mutagent/bin` | Where `mutagent install helix` writes the binary |
415
+ | `MUTAGENT_INSTALL_HOST` | `https://install.mutagent.io` | Where `mutagent install helix` downloads from |
416
+ | `MUTAGENT_HELIX_BIN` | `~/.mutagent/bin/helix`, then `helix` on `PATH` | Helix binary `mutagent agent run` uses |
417
+ | `MUTAGENT_BUN_BIN` | `bun` on `PATH` | Bun binary that compiles managed agents |
418
+ | `HELIX_CODING_AGENT_DIR` | `~/.mutagent/agent` | Local Helix login store that `mutagent providers mirror` reads |
419
+
420
+ Workspace precedence: `--workspace`, then `MUTAGENT_WORKSPACE_ID`, then the workspace chosen with
421
+ `mutagent workspaces use`.
422
+
423
+ ### Files
424
+
425
+ - `~/.config/mutagent/credentials.json`: the credentials `mutagent login` stores.
426
+ - `.mutagentrc.json`: project config written by `mutagent init` (the endpoint and the selected
427
+ workspace). An existing file is left untouched.
428
+
429
+ ## Links
430
+
431
+ - [Documentation](https://docs.mutagent.io/cli): installation, every command, JSON output, errors
432
+ - [Dashboard](https://app.mutagent.io)
433
+ - [mutagent.io](https://mutagent.io)
434
+ - Found a problem? `mutagent feedback send "<what happened>" --category cli`
737
435
 
738
436
  ## License
739
437
 
740
438
  Released under the [Apache License 2.0](./LICENSE).
741
-
742
- (c) 2026 MutagenT. All rights reserved.
743
-
744
- ---
745
-
746
- <p align="center">
747
- <sub>Built with care by the MutagenT Team</sub>
748
- </p>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mutagent/cli",
3
- "version": "0.2.59",
3
+ "version": "0.2.61",
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": {