@mutagent/cli 0.1.396 → 0.1.397

package/README.md

@@ -328,7 +328,7 @@ is the source of truth for flags.
 | Option | Description |
 |---|---|
 | `--json` | Output results as JSON (for AI agents) |
-| `--api-key <key>` | Mutagent API key for this command |
+| `--api-key <key>` | Mutagent platform API key for this command |
 | `--endpoint <url>` | Mutagent server endpoint for this command |
 | `--non-interactive` | Disable interactive prompts (for CI/AI agents) |
 | `-h, --help` | Display help for command |
@@ -381,7 +381,7 @@ mutagent providers get <id>         # LLM provider details
 mutagent providers test <id>        # Test LLM provider connectivity
 
 # Manage keys
-mutagent providers add              # Add a provider (--provider, --name, --api-key, --scope, --base-url, --set-default)
+mutagent providers add              # Add an LLM provider (--provider, --name, --api-key-stdin or --api-key, --base-url, --set-default)
 mutagent providers update <id> --name "New name" --active true
 mutagent providers delete <id> --force
 ```
@@ -392,12 +392,12 @@ LLM provider types: `openai`, `anthropic`, `google`, `moonshot`, `glm`, `deepsee
 #### Workspace Environments (`env`)
 
 ```bash
-mutagent env ls                                              # List the workspace's Environments
+mutagent env list                                            # List the workspace's Environments
 mutagent env set demo GREETING=hello --secret GITHUB_TOKEN=ghp_…
 mutagent env set staging --from-file .env.staging --secrets-from-file .env.staging.secrets
 mutagent env show demo                                       # Entry names + fingerprints — never a value
 mutagent env unset demo GREETING
-mutagent env rm demo --force
+mutagent env delete demo --force
 mutagent helix --env demo -p "check the deploy"              # Load it into a Helix cloud run
 ```
 
@@ -496,12 +496,12 @@ mutagent sandbox presets                          # Presets `mutagent helix --pr
 mutagent sandbox providers                        # Providers `mutagent helix --sandbox-provider` can name
 mutagent sandbox preflight --image alpine:3.20    # Would this definition run?
 mutagent sandbox spawn --image alpine:3.20 --detach
-mutagent sandbox ls
+mutagent sandbox list
 mutagent sandbox status sbx_1
 mutagent sandbox exec --sandbox sbx_1 -- bun test
 mutagent sandbox attach sbx_1 --since 412
 mutagent sandbox traces sbx_1                     # Spans recorded for a sandbox
-mutagent sandbox rm sbx_1 --force
+mutagent sandbox delete sbx_1 --force
 ```
 
 `exec` without `--sandbox` runs one command in a fresh, one-shot sandbox and
@@ -553,7 +553,7 @@ flowchart LR
   HXAGENT --> HXAGENTDEF["definition: positional, --prompt, --file, --name"]
   HXAGENT --> HXAGENTSLUG["@slug, @slug:vN, @slug:latest<br/>managed agent"]
 
-  HXSESSION --> SLS["ls"]
+  HXSESSION --> SLS["list"]
   HXSESSION --> SATTACH["attach"]
   HXSESSION --> SSEND["send"]
   HXSESSION --> SSIGNAL["signal"]
@@ -620,8 +620,8 @@ The two trees authenticate differently.
 | `helix --version`, `-v` | `GET /api/sandbox/presets` (the preset description, not a live probe) | `commands/helix/index.ts` → `commands/helix/doctor.ts` → `lib/sandbox-catalog.ts` |
 | `helix agent <definition> …` | `POST SESSIONS` with `arm: agent` (or `POST /api/sandbox/:id/session` with `--sandbox`), then the attach loop | `commands/helix/agent.ts` → `commands/helix/run-cloud.ts` |
 | `helix agent @slug[:vN\|:latest]` | `POST SESSIONS` with body `agent: {slug, revision?}`, `mode` when `-p` or `--rpc` is given, `args: ["-p", task]`; prints the receipt `{reference, sandboxId, agent, mode}` on stderr; then the attach loop | `commands/helix/agent.ts` → `commands/helix/managed-agent.ts` → `commands/helix/run-cloud.ts` |
-| `helix session ls` | `GET SESSIONS[?limit=&cursor=]` | `commands/helix/session-commands.ts` → `lib/helix-session-api.ts` |
-| `helix session ls <sandbox-id>` (internal) | `GET /api/sandbox/:id/sessions` | `commands/helix/session-commands.ts` → `lib/sandbox-api.ts` |
+| `helix session list` | `GET SESSIONS[?limit=&cursor=]` | `commands/helix/session-commands.ts` → `lib/helix-session-api.ts` |
+| `helix session list <sandbox-id>` (internal) | `GET /api/sandbox/:id/sessions` | `commands/helix/session-commands.ts` → `lib/sandbox-api.ts` |
 | `helix session attach <ref>` | `GET SESSIONS/<ref>/stream[?since=]` | `commands/helix/session-commands.ts` → `lib/helix-session-api.ts` |
 | `helix session send <ref>` | `POST SESSIONS/<ref>/input` `{line}` | `commands/helix/send.ts` → `lib/helix-session-api.ts` |
 | `helix session send <id> --session <sid>` (internal) | `POST /api/sandbox/:id/input` `{sessionId, line}` | `commands/helix/send.ts` → `lib/sandbox-api.ts` |
@@ -637,7 +637,7 @@ The two trees authenticate differently.
 | `helix models default <ids…>`, `--clear` | `PUT /api/sandbox/helix/defaults` `{models}` (`--clear` sends `[]`) | `commands/helix/models.ts` → `lib/sandbox-api.ts` |
 | `helix doctor`, `helix smoke` | `POST /api/sandbox/run` (fresh preset sandbox, torn down after), or `POST /api/sandbox/:id/exec` with `--sandbox` | `commands/helix/doctor.ts` → `lib/sandbox-api.ts` |
 | `helix version` | `GET /api/sandbox/presets` | `commands/helix/doctor.ts` → `lib/sandbox-catalog.ts` |
-| `helix update` | `GET /api/sandbox/presets` to name the pinned version, then exit 2 | `commands/helix/doctor.ts` |
+| `helix update` | `GET /api/sandbox/presets` to name the pinned version, then exit 1 (`NOT_SUPPORTED`) | `commands/helix/doctor.ts` |
 
 All source paths in this table are under `mutagent-cli/src/`.
 
@@ -694,17 +694,37 @@ mutagent skills install                  # Install the skill so agents can self-
 | `_links` | Dashboard / API URLs |
 | `_compat` | Compat metadata: `cliVersion`, `skillVersion`, `skillMinCliVersion` |
 
-#### Exit codes
+#### Exit codes and failures
+
+One table for every command (`EXIT_CODES` in `src/lib/errors.ts`):
 
 | Code | Meaning |
 |---|---|
 | `0` | Success |
-| `1` | General error |
-| `2` | Authentication required |
-| `3` | Configuration error |
-| `5` | Network error |
-| `6` | Rate limit exceeded |
-| `8` | Permission error |
+| `1` | Failure, usage errors included (unknown command or option, a missing argument) |
+| `2` | The API key expired or is invalid (a key from another service included) |
+| `3` | Not signed in, or no workspace selected |
+
+Exit 0 means success and nothing else: under `--json`, `success: true` if and only if the
+exit code is 0. A failure under `--json` is one object on stdout:
+
+```json
+{
+  "success": false,
+  "error": "What went wrong",
+  "code": "UNKNOWN_OPTION",
+  "suggestedAction": "Run: mutagent env ls --help",
+  "_agentGuidance": {
+    "helpCommand": "mutagent env ls --help",
+    "fix": ["mutagent env ls --help"],
+    "notes": [],
+    "escalate": "Present only when a person has to act"
+  }
+}
+```
+
+In a terminal the same failure is `Error: …` on stderr, with the fix. Commands that forward
+a remote process (`sandbox exec`, a Helix run) exit with that process's own code.
 
 ### See also