docs: update Sandboxes for the v0.48.0 CLI refactor (#26314)

## Summary Update the Sandbox documentation for the v0.48.0 CLI refactor: renamed flags, settings commands, terminal output, structured output, and non-interactive confirmations. Add a migration reference for scripts and CI workflows, with a [**Copy as prompt** button](https://deploy-preview-26314--docsdocker.netlify.app/ai/sandboxes/workflows/automation/#update-scripts-for-v0480) that copies agent instructions and the section Markdown. This PR targets `main` independently of the other PRs in the sbx/v0.48.0 milestone. It keeps the generated reference import separate from documentation edits: - Vendor the 120 generated CLI YAML files - Update command examples and guidance. Historical release notes retain their original command spellings. The other milestone PRs cover separate release features; this PR covers the CLI migration. @netlify /ai/sandboxes/workflows/automation/ Generated by Codex
2026-10-23 18:09:02 +03:00 · 2026-10-13 17:18:50 +02:00
parent 115d2302b8
commit c64e3927ef
116 changed files with 740 additions and 288 deletions
--- a/COMPONENTS.md
+++ b/COMPONENTS.md
@@ -336,6 +336,18 @@ Create styled buttons for calls to action.
 {{</* button text="Download Docker Desktop" url="/get-docker/" */>}}
 ```

+### Copy as prompt
+
+Wrap a section with `copy-as-prompt` to add a **Copy as prompt** button. The
+button copies the instruction followed by the section's source Markdown.
+The section remains visible and appears in the page's Markdown output.
+
+```markdown
+{{</* copy-as-prompt instruction="Update this project using the migration reference below." */>}}
+Migration reference content
+{{</* /copy-as-prompt */>}}
+```
+
 ### Cards

 Create card layouts for organizing content.
--- a/content/manuals/ai/sandboxes/cloud/usage.md
+++ b/content/manuals/ai/sandboxes/cloud/usage.md
@@ -86,7 +86,7 @@ For scripts or terminals without interactive input, start the sandbox without
 opening an agent session:

 ```console
-$ sbx --cloud run --detached claude --name cloud-task
+$ sbx --cloud run --detach claude --name cloud-task
 ```

 A detached run with `--name` reuses the named sandbox and starts it if stopped.
@@ -226,7 +226,7 @@ $ sbx --cloud attach cloud-project
 ```

 You can also use `sbx --cloud run claude --name cloud-project`, or run the agent
-without `--name` and select the sandbox when prompted. Add `--detached` to a
+without `--name` and select the sandbox when prompted. Add `--detach` to a
 named run to resume without attaching.

 Resuming keeps the sandbox ID and state, and starts a new time-to-live
@@ -258,7 +258,7 @@ $ sbx --cloud run --rm claude
 ```

 The detach gesture is turned off for that session, and you can't combine
-`--rm` with `--detached`. If the session ends without completing, for example
+`--rm` with `--detach`. If the session ends without completing, for example
 because the connection drops, the sandbox is kept and the CLI prints the
 command to remove it.

--- a/content/manuals/ai/sandboxes/configuration/credentials.md
+++ b/content/manuals/ai/sandboxes/configuration/credentials.md
@@ -334,8 +334,8 @@ List all stored secrets:

 ```console
 $ sbx secret ls
-SCOPE      TYPE      NAME      SECRET
-(global)   service   github    gho_GCaw4o****...****43qy
+SCOPE      SERVICE   SECRET
+(global)   github    gho_GCaw4o****...****43qy
 ```

 Remove a secret:
@@ -581,7 +581,7 @@ store or enter one at the prompt. For OAuth, you approve the sign-in flow. In
 both cases, you approve the domains declared by the kit. `sbx` writes the entry
 to `credentials.yaml`.

-In non-interactive contexts (CI or `--detached`), there's no one to answer the
+In non-interactive contexts (CI or `--detach`), there's no one to answer the
 prompt. In `sbx`, the sandbox starts with the credential withheld when no
 binding exists. For a required credential, `sbx` prints a warning rather than
 failing sandbox creation. This is a limitation of `sbx` enforcement: kit authors
--- a/content/manuals/ai/sandboxes/configuration/environment-files.md
+++ b/content/manuals/ai/sandboxes/configuration/environment-files.md
@@ -366,14 +366,14 @@ Automation can create the sandbox without attaching, run commands in it, and
 remove it afterward:

 ```console
-$ sbx env create --auto-approve
+$ sbx env create --force
 $ sbx env exec -- npm test
 $ sbx env rm --force
 ```

-`--auto-approve` approves the plan for that invocation without recording
-consent for later invocations. Use the flag for each unattended `create` or
-`run`. The `--force` flag approves the destroy plan and removes the sandbox even
+For `create` and `run`, `--force` approves the plan for that invocation without
+recording consent for later invocations. Use the flag for each unattended `create` or
+`run`. For `rm`, `--force` approves the destroy plan and removes the sandbox even
 when it is in use.

 Commands and vault references under `secrets` resolve on the host, so the
@@ -528,7 +528,7 @@ Read the symbol beside each entry before approving the plan:
 Interactive approval is recorded for the environment under the `sbx` state
 directory. Plans without host commands apply silently on later invocations until
 the environment changes or a resource is missing. An approval provided with
-`--auto-approve` applies only to that invocation.
+`--force` applies only to that invocation.

 ## Update an environment

@@ -755,7 +755,7 @@ commands.

 Plans containing lifecycle commands or credential `command` sources require
 approval for every invocation by default, even when the command text hasn't
-changed. Approve one invocation with `--auto-approve`, skip lifecycle commands
+changed. Approve one invocation with `--force`, skip lifecycle commands
 with `--skip-host-commands`, or turn on
 [`env.rememberHostCommands`](settings.md#envrememberhostcommands) to remember
 approval until the commands change:
--- a/content/manuals/ai/sandboxes/configuration/settings.md
+++ b/content/manuals/ai/sandboxes/configuration/settings.md
@@ -19,11 +19,11 @@ necessary. Overrides persist across CLI invocations and daemon restarts.
 List settings with their effective value, type, source, and description:

 ```console
-$ sbx settings list
+$ sbx settings ls
 ```

 Long values and descriptions are truncated in the table. Use
-`sbx settings list --no-trunc` for complete text, or `sbx settings list --json`
+`sbx settings ls --no-trunc` for complete text, or `sbx settings ls --json`
 for JSON output. The JSON records also include defaults and environment
 variable names where available.

@@ -35,8 +35,8 @@ false
 $ sbx settings get clipboard.imagePaste --json
 ```

-Without `--json`, `get` prints only the effective value. With `--json`, it
-prints the complete setting record, including the source and default.
+By default, `get` prints only the effective value. Use `--json` or
+`--format yaml` for the complete setting record, including the source and default.

 ## Change a setting

@@ -74,7 +74,7 @@ For each setting, the first available value wins:
 2. A user override written with `sbx settings set`
 3. The built-in default

-The `SOURCE` column in `sbx settings list` identifies the selected source as
+The `SOURCE` column in `sbx settings ls` identifies the selected source as
 `envvar`, `override`, or `default`. If an environment variable takes precedence,
 `set` still updates the stored override and reports why the effective value
 hasn't changed. `unset` removes only the stored override, not the environment
@@ -130,7 +130,7 @@ export a variable in each shell.

 Each entry lists its built-in default, before overrides. An environment
 variable appears only when the setting has a direct equivalent. Use
-`sbx settings list` to inspect the values supported by your installed version.
+`sbx settings ls` to inspect the values supported by your installed version.

 ### Agents and host access

@@ -182,7 +182,7 @@ $ sbx settings set env.rememberHostCommands true

 The first approval is still required. Commands run on your host with your
 permissions, outside the sandbox. Leave the setting at `false` to require
-approval on every invocation, or use `--auto-approve` to approve only one
+approval on every invocation, or use `--force` to approve only one
 invocation. See [environment lifecycle commands](environment-files.md#lifecycle).

 #### ssh.agentForwardingEnabled {.wrap-anywhere}
@@ -664,9 +664,9 @@ and the consequences of sharing a writable store.

 ## Command reference

-### sbx settings list
+### sbx settings ls

-List settings. Alias: `sbx settings ls`.
+List settings. Alias: `sbx settings list`.

 Use `--json` for complete records as JSON, or `--no-trunc` for full text. These
 options are mutually exclusive.
--- a/content/manuals/ai/sandboxes/customize/author/_index.md
+++ b/content/manuals/ai/sandboxes/customize/author/_index.md
@@ -219,7 +219,7 @@ capabilities:
 ```

 A sandbox created with this kit behaves like one started with
-[`sbx run --detached`](/manuals/ai/sandboxes/usage.md#keep-a-sandbox-running-in-the-background):
+[`sbx run --detach`](/manuals/ai/sandboxes/usage.md#keep-a-sandbox-running-in-the-background):
 it keeps running until someone stops or removes it, including after you attach
 to it and disconnect. When a workload, mixin, or set declares the capability,
 it applies to the whole sandbox.
--- a/content/manuals/ai/sandboxes/get-started.md
+++ b/content/manuals/ai/sandboxes/get-started.md
@@ -93,14 +93,14 @@ From another terminal, list your sandboxes:

 ```console
 $ sbx ls
-SANDBOX       AGENT    STATUS    PORTS   WORKSPACE
-my-sandbox    claude   running           ~/my-project
+SANDBOX      AGENT    STATUS      PORTS   WORKSPACE      CREATED
+my-sandbox   claude   ● running           ~/my-project   2m
 ```

-Each row shows a sandbox's name, the agent running in it, its status, any
-[published ports](usage.md#publish-ports), and its
-workspace — the host directory shared into the sandbox. That workspace is the
-one part of your machine the agent can see.
+Each row shows a sandbox's name, agent, status,
+[published ports](usage.md#publish-ports), workspace, and age. The workspace is
+the host directory shared into the sandbox and the one part of your machine
+the agent can see.

 When you run `sbx run` from a project directory without passing a workspace
 path, the current directory is mounted read-write. The agent and your host see
--- a/content/manuals/ai/sandboxes/governance/access-controls/local.md
+++ b/content/manuals/ai/sandboxes/governance/access-controls/local.md
@@ -295,12 +295,12 @@ a network request with `sbx policy check network`:

 ```console
 $ sbx policy check network api.anthropic.com
-Allowed: api.anthropic.com
-
 $ sbx policy check network blocked.example.com
-Denied: blocked.example.com
 ```

+The output reports `Allowed` or `Denied`, along with governance and context
+details. A denied check returns a non-zero exit status.
+
 The target can be a hostname, a `host:port` pair, an IP address, or a URL.
 Bare hostnames and IP addresses are evaluated against port 443. This is useful
 for verifying custom rules or checking what the Locked Down preset blocks
@@ -340,7 +340,7 @@ $ sbx policy reset --force

 If rules you add with `sbx policy allow` don't change sandbox behavior, your
 organization likely has governance enabled. Run `sbx policy ls` to check: if
-the output starts with a `Governance:` status line showing `Managed by <org>`,
+the summary block contains `Governance: Managed by <org>`,
 org governance is active. When it's active, local allow rules are inactive.
 You can't use them to loosen restrictions the org policy imposes.

--- a/content/manuals/ai/sandboxes/governance/access-controls/network.md
+++ b/content/manuals/ai/sandboxes/governance/access-controls/network.md
@@ -156,22 +156,12 @@ To inspect a single entry, pass its ID to `sbx policy approval inspect`:

 ```console
 $ sbx policy approval inspect network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY
-APPROVAL network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY  (sandbox: my-sandbox)
-  api.example.com:443
-  Protocol: TCP
-  Resource type: domain
-  approval required by policy "default network"
-
-  OPTION    LABEL
-  allow     Allow
-  dismiss   Dismiss
 ```

 Respond by selecting one of the options the entry offers:

 ```console
 $ sbx policy approval respond network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY --option allow
-Recorded: Allow
 ```

 Choosing `allow` grants access to that destination. Choosing `dismiss` leaves
--- a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md
+++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md
@@ -66,13 +66,16 @@ See [Approval-required access](../access-controls/network.md#approval-required-a
 A `STATUS` column also appears when you pass `--include-inactive`; see
 [Showing inactive rules](#showing-inactive-rules).

-When organization governance is active, the output starts with a summary line
+When organization governance is active, the output starts with a summary block
 showing which organization manages the policy, the sync state, and how many
 inactive rules are hidden:

 ```console
 $ sbx policy ls
-Governance: Managed by my-org | Sync: OK, last synced 08:21:01 | Hidden: 9 inactive rules. Show with: sbx policy ls --include-inactive
+POLICY RULES
+  Governance: Managed by my-org
+  Sync:       OK, last synced 08:21:01
+  Hidden:     9 inactive rules. Show with: sbx policy ls --include-inactive

 POLICY               SOURCE   APPLIES TO   SUMMARY
 default filesystem   org      all          filesystem read: 2 allow; filesystem write: 7 allow, 2 deny
@@ -102,7 +105,9 @@ example, to confirm which allow rules the organization policy overrides — pass

 ```console
 $ sbx policy ls --include-inactive
-Governance: Managed by my-org | Sync: OK, last synced 08:41:06
+POLICY RULES
+  Governance: Managed by my-org
+  Sync:       OK, last synced 08:41:06

 POLICY                       SOURCE   APPLIES TO   SUMMARY                                                    STATUS
 default filesystem           org      all          filesystem read: 2 allow; filesystem write: 7 allow, 2 deny   active
@@ -189,11 +194,11 @@ which rules matched:

 ```console
 $ sbx policy log
-Blocked requests:
+BLOCKED REQUESTS
 SANDBOX      TYPE     HOST                   PROXY        RULE            REASON         LAST SEEN        COUNT
 my-sandbox   network  blocked.example.com    transparent  domain-blocked  default-deny   10:15:25 29-Jan  1

-Allowed requests:
+ALLOWED REQUESTS
 SANDBOX      TYPE     HOST                   PROXY          RULE             REASON   LAST SEEN        COUNT
 my-sandbox   network  api.anthropic.com      forward        domain-allowed            10:15:23 29-Jan  42
 my-sandbox   network  registry.npmjs.org     forward-bypass domain-allowed            10:15:20 29-Jan  18
@@ -219,7 +224,12 @@ Filter by sandbox name by passing it as an argument:
 $ sbx policy log my-sandbox
 ```

-Use `--limit N` to show only the last `N` entries, `--json` for
+Use `--limit N` to show only the last `N` entries, `--json` or `--format yaml` for
 machine-readable output, or `--type network` to filter by policy type.
 `sbx policy log` records network traffic only; filesystem mount decisions
 aren't available in the log yet.
+
+Structured output uses the same document for local and cloud sandboxes:
+`{updated_at, allowed: [...], blocked: [...]}`. Each entry includes `sandbox_id`,
+`host`, `proxy_type`, `rule`, `reason`, `count`, `first_seen`, and `last_seen`.
+The `--limit` flag applies to structured output too.
--- a/content/manuals/ai/sandboxes/mcp-gateway.md
+++ b/content/manuals/ai/sandboxes/mcp-gateway.md
@@ -50,10 +50,10 @@ the registration. After registration, verify that the server is registered:

 ```console
 $ sbx mcp ls
-NAME                 TYPE     URL/COMMAND
-notion               remote   https://mcp.notion.com/mcp
 ```

+The listing shows each server's transport, status, gateway, and details.
+
 Then start a sandbox and expose the registered server:

 ```console
@@ -261,11 +261,6 @@ authorization flow by default:

 ```console
 $ sbx mcp add notion --url https://mcp.notion.com/mcp
-Resolving MCP server "notion"...
-Open this URL to authorize MCP server "notion":
-https://api.notion.com/v1/oauth/authorize?...
-MCP server "notion" authorized
-MCP server "notion" registered (type: remote)
 ```

 OAuth credentials stay on the host. In local gateway mode, `sbx` stores tokens
@@ -497,7 +492,6 @@ To attach an already-registered server to a running sandbox, use
 ```console
 $ sbx mcp add linear --url https://mcp.linear.app/mcp
 $ sbx mcp load linear --sandbox my-session
-MCP server "linear" loaded into sandbox "my-session" (live)
 ```

 Connected agent sessions receive a tool-list update, so the added tools become
--- a/content/manuals/ai/sandboxes/troubleshooting.md
+++ b/content/manuals/ai/sandboxes/troubleshooting.md
@@ -24,8 +24,8 @@ $ sbx diagnose
 ```

 The command prints a summary of checks that passed, warned, or failed, along
-with suggested fixes. Use `--output json` to get machine-readable output, or
-`--output github-issue` to generate a Markdown snippet suitable for pasting
+with suggested fixes. Use `--json` or `--format yaml` for machine-readable
+output, or `--format github-issue` to generate a Markdown snippet suitable for pasting
 into a GitHub issue.

 ## Sandbox is not responding
@@ -142,7 +142,6 @@ allowlist:

 ```console
 $ sbx run claude --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=vale"
-ERROR: resolve kits: kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=vale" cannot be installed — its source is not in your allowlist.
 ```

 `sbx` restricts kit installs to an allowlist of sources, which defaults to
@@ -375,7 +374,7 @@ though the directory is a valid Git repository:

 ```console
 > sbx run --clone claude \\wsl.localhost\Ubuntu\home\you\repo
-ERROR: --clone requires a Git repository, but \\wsl.localhost\Ubuntu\home\you\repo is not in a Git repository
+error: --clone requires a Git repository, but \\wsl.localhost\Ubuntu\home\you\repo is not in a Git repository
 ```

 The cause is Git's dubious ownership check. When Git on Windows accesses a
@@ -393,7 +392,6 @@ the command again:
 ```console
 > git config --global --add safe.directory '%(prefix)///wsl.localhost/Ubuntu/home/you/repo'
 > sbx run --clone claude \\wsl.localhost\Ubuntu\home\you\repo
-✓ Git repository detected: \\wsl.localhost\Ubuntu\home\you\repo
 ```

 ## SSH agent socket is missing
@@ -479,7 +477,7 @@ If you downgrade `sbx` to a version older than the one that last managed your
 local state, the daemon may fail to start with a database version mismatch:

 ```text
-ERROR: failed to start backend in-process: start backend: creating containerd
+error: failed to start backend in-process: start backend: creating containerd
 server: ... database is at major version 6, but this binary only supports up
 to major version 1
 ```
@@ -565,3 +563,7 @@ The bundle contains daemon logs, diagnostic check results, and basic system
 information. When `--upload` is confirmed, the bundle is uploaded to Docker
 support and the command prints a diagnostics ID. Include this ID in your
 issue so the team can correlate it with the uploaded bundle.
+
+Without terminal input, `sbx diagnose --upload` saves the bundle locally and
+skips the upload. Check for a diagnostics ID to confirm that the upload
+succeeded.
--- a/content/manuals/ai/sandboxes/usage.md
+++ b/content/manuals/ai/sandboxes/usage.md
@@ -9,7 +9,9 @@ This page describes local sandboxes. For cloud commands, file transfers, ports,
 and expiration, see [Use cloud sandboxes](cloud/usage.md).

 Use this page as a command-oriented guide to day-to-day `sbx` operations. For
-scenario-based recommendations, see [Workflow patterns](workflows/).
+scenario-based recommendations, see [Workflow patterns](workflows/). For script
+output and the v0.48.0 CLI migration, see
+[CI and headless use](workflows/automation.md#update-scripts-for-v0480).

 ## Sign in

@@ -82,7 +84,7 @@ to start, the sandbox is also removed. If you reattach to an existing sandbox
 with `--rm`, that sandbox is removed only after its agent session finishes.

 `--rm` needs an attached agent session to know when to remove the sandbox, so
-you can't combine it with `--detached` or `--detach-keys`.
+you can't combine it with `--detach` or `--detach-keys`.

 ## Choose a workspace

@@ -173,7 +175,7 @@ sessions keep it running. Its files and configuration persist. Running

 To keep a sandbox running after every session ends, for example to serve an
 application on a [published port](#publish-ports), start it with
-`sbx run --detached` (`-d`). The command starts the sandbox, prints its ID,
+`sbx run --detach` (`-d`). The command starts the sandbox, prints its ID,
 and returns without opening an agent session:

 ```console
@@ -288,6 +290,9 @@ to switch between the sandboxes panel and the network panel.
 From the network panel you can browse connection logs, allow or block specific
 hosts, and add custom network rules. Press `?` to see all keyboard shortcuts.

+At selection and text prompts, Enter accepts the default. Ctrl-D cancels the
+prompt. Declining a required confirmation returns a non-zero exit status.
+
 ## Git workspace modes

 When your primary workspace is a Git repository, choose how the sandbox receives
@@ -410,12 +415,13 @@ $ sbx ports my-sandbox
 ```

 `sbx ls` shows active port mappings alongside each sandbox. `sbx ports` lists
-them in detail.
+them in detail. The `CREATED` column shows the sandbox age, and the `STATUS`
+column identifies sandboxes kept running in detached mode with `(detached)`.

 ```console
 $ sbx ls
-SANDBOX         AGENT   STATUS   PORTS                    WORKSPACE
-my-sandbox      claude  running  127.0.0.1:8080->3000/tcp4 /home/user/proj
+SANDBOX      AGENT    STATUS      PORTS                       WORKSPACE         CREATED
+my-sandbox   claude   ● running   127.0.0.1:8080->3000/tcp4    /home/user/proj    2m
 ```

 To stop forwarding a port:
@@ -514,13 +520,9 @@ Changes to user-level agent configuration files, such as
 persist in saved templates.

 If the saved template was built for a different agent than the one you
-specify in `sbx run`, you get a warning. For example, saving a Claude
-sandbox and running it with `codex` produces:
-
-```text
-⚠ WARNING: template "my-template:v1" was built for the "claude" agent but you are using "codex".
-  The sandbox may not work correctly. Consider using: sbx run -t my-template:v1 claude
-```
+specify in `sbx run`, the CLI prints a warning to stderr with a suggested
+command. For example, saving a Claude sandbox and running it with `codex`
+suggests `sbx run -t my-template:v1 claude`.

 ## Load a template

--- a/content/manuals/ai/sandboxes/workflows/automation.md
+++ b/content/manuals/ai/sandboxes/workflows/automation.md
@@ -20,12 +20,17 @@ Generate a PAT from your
 [Docker account settings](https://app.docker.com/settings/personal-access-tokens)
 with at least **Read** scope.

+Sign in before running commands that require authentication. Read-only commands
+and commands run with `--force` do not open an interactive sign-in flow.
+Create workspace directories before calling `sbx create` or `sbx run`: without
+a terminal, these commands fail if a workspace directory does not exist.
+
 Create the sandbox in the background with `sbx create`, run agent tasks with
 `sbx exec`, and remove the sandbox when finished:

 ```console
 $ sbx create --name ci-task --clone claude .
-$ sbx run --name ci-task  # attach and give instructions, or use sbx exec for one-off commands
+$ sbx exec ci-task -- claude --dangerously-skip-permissions -p "Review the code and commit your changes"
 $ git fetch sandbox-ci-task
 $ sbx rm --force ci-task
 ```
@@ -44,16 +49,79 @@ To overwrite an existing stored entry, add `--force`. To pass a value from your
 CI provider's secret store, use `-t`. For example, in a GitHub Actions step:

 ```yaml
- run: sbx secret set anthropic -t "${{ secrets.ANTHROPIC_API_KEY }}"
+- run: sbx secret set anthropic --force -t "${{ secrets.ANTHROPIC_API_KEY }}"
 ```

 ## Cleanup and exit codes

-Use `--force` to skip confirmation when removing resources in scripts.
-Declining a removal or required-restart prompt returns a non-zero exit code.
+Confirmations require terminal input. Piping an answer, such as `echo y`, does
+not confirm an operation. Use `--force` on commands that provide it to skip
+confirmation in scripts. `sbx kit builder history rm` uses `--yes` or `-y`
+instead, because its `--force` flag is passed to Buildx.
+
+A command that requires confirmation fails with exit status 1 when stdin is
+not a terminal. Declining a confirmation also returns a non-zero exit code.
 Treat this as an incomplete operation when deciding whether to continue a
 script.

 For repeatable cleanup, check which resources exist before removing them. For
 example, use `sbx mcp ls` before `sbx mcp rm`, which fails for an unregistered
 server even with `--force`.
+
+## Parse command output
+
+Use `--format json` or `--format yaml` on commands that support structured
+output. Human-readable tables and messages can change between releases.
+Results go to stdout. Errors, warnings, hints, and progress go to stderr.
+
+```console
+$ sbx ls --json | jq -r '.[].name'
+$ sbx prune --dry-run --format yaml
+```
+
+`--json` is an alias for `--format json`. On commands with shared output flags,
+`--format`, `--json`, and `--quiet` (`-q`) are mutually exclusive, even when
+`--json` and `--format json` request the same format. Unsupported format values
+are rejected. `sbx events --json` emits newline-delimited JSON, and
+`sbx mcp auth --format text|json` uses command-specific formats.
+
+### Update scripts for v0.48.0
+
+{{< copy-as-prompt instruction="Update this repository's Docker Sandboxes CLI usage for v0.48.0 using the migration reference below. Inspect scripts and documentation, update affected commands and output parsers, and verify the changes. Preserve unrelated behavior." >}}
+
+Docker Sandboxes v0.48.0 changes flags and structured output. Update scripts
+that use the following flags:
+
+| Command | Previous flag | Replacement |
+| --- | --- | --- |
+| `sbx run`, `sbx env run` | `--detached` | `--detach` or `-d` |
+| `sbx logout` | `--yes`, `-y` | `--force` or `-f` |
+| `sbx env create`, `sbx env run` | `--auto-approve`, `-y` | `--force` or `-f` |
+| `sbx create` | `--quiet`, `-q` | `--no-progress` suppresses progress but still prints the creation summary |
+| `sbx template save` | `-d` for a description | `--description` |
+| `sbx diagnose` | `--output`, `-o` | `--format table`, `json`, `yaml`, or `github-issue` |
+| `sbx policy log` | `--quiet`, `-q` | Removed without a replacement |
+
+`sbx settings ls` is the primary command spelling. `sbx settings list` remains
+an alias. Replace the deprecated `sbx mcp add --skip_auth` with `--skip-auth`.
+Secret commands that default to global scope still accept the deprecated
+`--global` flag but print a warning to stderr. Omit the flag for those commands.
+
+JSON field names use `snake_case`. YAML uses the same representation. Update
+parsers for these commands:
+
+| Command | Structured output in v0.48.0 |
+| --- | --- |
+| `sbx ls` | A sandbox array, replacing `{sandboxes: [...]}`. `created_at` and `last_used_at` use RFC 3339 timestamps. Rows include `detached`. |
+| `sbx template ls` | An image array, replacing `{images: [...]}`. |
+| Local `sbx mcp ls` | A server array, replacing `{gateway: {...}, servers: [...]}`. Each row includes `gateway`. Cloud rows describe server usage across sandboxes and differ from local registration rows. |
+| `sbx policy log` | `{updated_at, allowed: [...], blocked: [...]}` for local and cloud output. See [Monitoring traffic](/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md#monitoring-traffic). |
+| `sbx --cloud policy ls` | Field names use `snake_case` instead of camelCase. |
+| `sbx ports` | Local rows contain `host_ip`, `host_port`, `sandbox_port`, and `protocol`. Cloud rows contain `sandbox_port` and `url`, replacing `port`. Local publish and unpublish results include `action: published` or `action: unpublished`. |
+| Cloud `sbx volume create`, `sbx volume ls`, `sbx volume inspect` | Fields such as `ID`, `Name`, and `CreatedAt` become `id`, `name`, and `created_at`. `volume inspect` defaults to human-readable details, so request a structured format explicitly. |
+| `sbx rm`, `sbx stop`, `sbx template rm`, `sbx volume rm` | An array of results with `action`, `resource`, `name`, and optional `id` and `error`, including missing or failed targets. Actions are lowercase: `removed`, `stopped`, `removing`, `stopping`, or `failed`. |
+
+For example, replace the jq filter `.sandboxes[].name` with `.[].name` when
+extracting sandbox names from `sbx ls --json`.
+
+{{< /copy-as-prompt >}}
--- a/content/manuals/ai/sandboxes/workflows/development.md
+++ b/content/manuals/ai/sandboxes/workflows/development.md
@@ -73,8 +73,8 @@ lists them in detail:

 ```console
 $ sbx ls
-SANDBOX         AGENT   STATUS   PORTS                    WORKSPACE
-my-sandbox      claude  running  127.0.0.1:8080->3000/tcp4 /home/user/proj
+SANDBOX      AGENT    STATUS      PORTS                       WORKSPACE         CREATED
+my-sandbox   claude   ● running   127.0.0.1:8080->3000/tcp4    /home/user/proj    2m
 ```

 To stop forwarding a port:
--- a/data/sbx_cli/sbx.yaml
+++ b/data/sbx_cli/sbx.yaml
@@ -45,7 +45,7 @@ see_also:
    - sbx skills - (Experimental) Manage skills available in sandboxes
    - sbx stop - Stop one or more sandboxes without removing them
    - sbx template - Manage sandbox templates
-    - sbx ttl - Inspect or extend a cloud sandbox's TTL
+    - sbx ttl - Show or extend a cloud sandbox's TTL
    - sbx tui - Open the interactive TUI dashboard
    - sbx version - Show Docker Sandboxes version information
    - sbx volume - Manage persistent volumes (cloud-only)
--- a/data/sbx_cli/sbx_completion_bash.yaml
+++ b/data/sbx_cli/sbx_completion_bash.yaml
@@ -39,5 +39,11 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      # Load completions in the current shell
+      source <(sbx completion bash)
+
+      # Install for every new shell
+      sbx completion bash > /etc/bash_completion.d/sbx
 see_also:
    - sbx completion - Generate the autocompletion script for the specified shell
--- a/data/sbx_cli/sbx_completion_fish.yaml
+++ b/data/sbx_cli/sbx_completion_fish.yaml
@@ -30,5 +30,11 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      # Load completions in the current shell
+      sbx completion fish | source
+
+      # Install for every new shell
+      sbx completion fish > ~/.config/fish/completions/sbx.fish
 see_also:
    - sbx completion - Generate the autocompletion script for the specified shell
--- a/data/sbx_cli/sbx_completion_powershell.yaml
+++ b/data/sbx_cli/sbx_completion_powershell.yaml
@@ -27,5 +27,11 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      # Load completions in the current session
+      sbx completion powershell | Out-String | Invoke-Expression
+
+      # Install for every new session
+      sbx completion powershell >> $PROFILE
 see_also:
    - sbx completion - Generate the autocompletion script for the specified shell
--- a/data/sbx_cli/sbx_completion_zsh.yaml
+++ b/data/sbx_cli/sbx_completion_zsh.yaml
@@ -41,5 +41,11 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      # Load completions in the current shell
+      source <(sbx completion zsh)
+
+      # Install for every new shell
+      sbx completion zsh > "${fpath[1]}/_sbx"
 see_also:
    - sbx completion - Generate the autocompletion script for the specified shell
--- a/data/sbx_cli/sbx_cp.yaml
+++ b/data/sbx_cli/sbx_cp.yaml
@@ -9,7 +9,7 @@ description: |-
    When copying a directory, the directory itself is placed at the destination.
    If the destination path does not exist it is created; if it already exists
    as a directory, the source is placed inside it.
-usage: sbx cp [flags] SRC DST
+usage: sbx cp SRC DST [flags]
 options:
    - name: follow-link
      shorthand: L
--- a/data/sbx_cli/sbx_create.yaml
+++ b/data/sbx_cli/sbx_create.yaml
@@ -28,7 +28,7 @@ description: |-
    "sbx --cloud policy init <allow-all|balanced|deny-all>".

    Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation.
-usage: sbx create [flags] AGENT|SANDBOX_KIT [PATH...]
+usage: sbx create AGENT|SANDBOX_KIT [PATH...] [flags]
 options:
    - name: allow-network
      usage: |
@@ -82,6 +82,9 @@ options:
    - name: name
      usage: |
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
+    - name: no-progress
+      default_value: "false"
+      usage: Suppress progress output
    - name: on-timeout
      usage: |
        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
@@ -91,12 +94,8 @@ options:
      usage: |
        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
    - name: pull
-      default_value: always
-      usage: Image pull policy (always|missing|never)
-    - name: quiet
-      shorthand: q
-      default_value: "false"
-      usage: Suppress verbose output
+      usage: |
+        Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always)
    - name: skills
      usage: |
        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
--- a/data/sbx_cli/sbx_create_claude.yaml
+++ b/data/sbx_cli/sbx_create_claude.yaml
@@ -89,6 +89,9 @@ inherited_options:
    - name: name
      usage: |
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
+    - name: no-progress
+      default_value: "false"
+      usage: Suppress progress output
    - name: on-timeout
      usage: |
        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
@@ -98,12 +101,8 @@ inherited_options:
      usage: |
        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
    - name: pull
-      default_value: always
-      usage: Image pull policy (always|missing|never)
-    - name: quiet
-      shorthand: q
-      default_value: "false"
-      usage: Suppress verbose output
+      usage: |
+        Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always)
    - name: skills
      usage: |
        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
--- a/data/sbx_cli/sbx_create_codex.yaml
+++ b/data/sbx_cli/sbx_create_codex.yaml
@@ -89,6 +89,9 @@ inherited_options:
    - name: name
      usage: |
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
+    - name: no-progress
+      default_value: "false"
+      usage: Suppress progress output
    - name: on-timeout
      usage: |
        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
@@ -98,12 +101,8 @@ inherited_options:
      usage: |
        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
    - name: pull
-      default_value: always
-      usage: Image pull policy (always|missing|never)
-    - name: quiet
-      shorthand: q
-      default_value: "false"
-      usage: Suppress verbose output
+      usage: |
+        Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always)
    - name: skills
      usage: |
        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
--- a/data/sbx_cli/sbx_create_cursor.yaml
+++ b/data/sbx_cli/sbx_create_cursor.yaml
@@ -89,6 +89,9 @@ inherited_options:
    - name: name
      usage: |
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
+    - name: no-progress
+      default_value: "false"
+      usage: Suppress progress output
    - name: on-timeout
      usage: |
        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
@@ -98,12 +101,8 @@ inherited_options:
      usage: |
        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
    - name: pull
-      default_value: always
-      usage: Image pull policy (always|missing|never)
-    - name: quiet
-      shorthand: q
-      default_value: "false"
-      usage: Suppress verbose output
+      usage: |
+        Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always)
    - name: skills
      usage: |
        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
--- a/data/sbx_cli/sbx_create_devin.yaml
+++ b/data/sbx_cli/sbx_create_devin.yaml
@@ -89,6 +89,9 @@ inherited_options:
    - name: name
      usage: |
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
+    - name: no-progress
+      default_value: "false"
+      usage: Suppress progress output
    - name: on-timeout
      usage: |
        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
@@ -98,12 +101,8 @@ inherited_options:
      usage: |
        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
    - name: pull
-      default_value: always
-      usage: Image pull policy (always|missing|never)
-    - name: quiet
-      shorthand: q
-      default_value: "false"
-      usage: Suppress verbose output
+      usage: |
+        Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always)
    - name: skills
      usage: |
        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
--- a/data/sbx_cli/sbx_create_docker-agent.yaml
+++ b/data/sbx_cli/sbx_create_docker-agent.yaml
@@ -89,6 +89,9 @@ inherited_options:
    - name: name
      usage: |
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
+    - name: no-progress
+      default_value: "false"
+      usage: Suppress progress output
    - name: on-timeout
      usage: |
        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
@@ -98,12 +101,8 @@ inherited_options:
      usage: |
        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
    - name: pull
-      default_value: always
-      usage: Image pull policy (always|missing|never)
-    - name: quiet
-      shorthand: q
-      default_value: "false"
-      usage: Suppress verbose output
+      usage: |
+        Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always)
    - name: skills
      usage: |
        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
--- a/data/sbx_cli/sbx_create_gemini.yaml
+++ b/data/sbx_cli/sbx_create_gemini.yaml
@@ -89,6 +89,9 @@ inherited_options:
    - name: name
      usage: |
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
+    - name: no-progress
+      default_value: "false"
+      usage: Suppress progress output
    - name: on-timeout
      usage: |
        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
@@ -98,12 +101,8 @@ inherited_options:
      usage: |
        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
    - name: pull
-      default_value: always
-      usage: Image pull policy (always|missing|never)
-    - name: quiet
-      shorthand: q
-      default_value: "false"
-      usage: Suppress verbose output
+      usage: |
+        Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always)
    - name: skills
      usage: |
        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
--- a/data/sbx_cli/sbx_create_opencode.yaml
+++ b/data/sbx_cli/sbx_create_opencode.yaml
@@ -89,6 +89,9 @@ inherited_options:
    - name: name
      usage: |
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
+    - name: no-progress
+      default_value: "false"
+      usage: Suppress progress output
    - name: on-timeout
      usage: |
        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
@@ -98,12 +101,8 @@ inherited_options:
      usage: |
        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
    - name: pull
-      default_value: always
-      usage: Image pull policy (always|missing|never)
-    - name: quiet
-      shorthand: q
-      default_value: "false"
-      usage: Suppress verbose output
+      usage: |
+        Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always)
    - name: skills
      usage: |
        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
--- a/data/sbx_cli/sbx_create_shell.yaml
+++ b/data/sbx_cli/sbx_create_shell.yaml
@@ -89,6 +89,9 @@ inherited_options:
    - name: name
      usage: |
        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods (periods are rejected with --cloud); 'default' is reserved)
+    - name: no-progress
+      default_value: "false"
+      usage: Suppress progress output
    - name: on-timeout
      usage: |
        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
@@ -98,12 +101,8 @@ inherited_options:
      usage: |
        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
    - name: pull
-      default_value: always
-      usage: Image pull policy (always|missing|never)
-    - name: quiet
-      shorthand: q
-      default_value: "false"
-      usage: Suppress verbose output
+      usage: |
+        Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always)
    - name: skills
      usage: |
        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
--- a/data/sbx_cli/sbx_daemon.yaml
+++ b/data/sbx_cli/sbx_daemon.yaml
@@ -17,8 +17,8 @@ inherited_options:
      usage: Enable debug logging
 see_also:
    - sbx - Manage AI coding agent sandboxes.
-    - sbx daemon log-level - Inspect or change sandboxd's per-category log levels
+    - sbx daemon log-level - Show or change sandboxd's per-category log levels
    - sbx daemon restart - Restart the sandboxd daemon
    - sbx daemon start - Start the sandboxd daemon
-    - sbx daemon status - Check sandboxd daemon status
+    - sbx daemon status - Show sandboxd daemon status
    - sbx daemon stop - Stop the sandboxd daemon
--- a/data/sbx_cli/sbx_daemon_log-level.yaml
+++ b/data/sbx_cli/sbx_daemon_log-level.yaml
@@ -1,5 +1,5 @@
 name: sbx daemon log-level
-synopsis: Inspect or change sandboxd's per-category log levels
+synopsis: Show or change sandboxd's per-category log levels
 usage: sbx daemon log-level [COMMAND]
 options:
    - name: help
--- a/data/sbx_cli/sbx_daemon_log-level_set.yaml
+++ b/data/sbx_cli/sbx_daemon_log-level_set.yaml
@@ -1,6 +1,6 @@
 name: sbx daemon log-level set
 synopsis: 'Set a category''s log level (target: proxy, general, or all)'
-usage: sbx daemon log-level set <target> <level> [flags]
+usage: sbx daemon log-level set TARGET LEVEL [flags]
 options:
    - name: help
      shorthand: h
@@ -15,5 +15,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx daemon log-level set proxy debug
+
+      # Every category at once
+      sbx daemon log-level set all info
 see_also:
-    - sbx daemon log-level - Inspect or change sandboxd's per-category log levels
+    - sbx daemon log-level - Show or change sandboxd's per-category log levels
--- a/data/sbx_cli/sbx_daemon_restart.yaml
+++ b/data/sbx_cli/sbx_daemon_restart.yaml
@@ -15,5 +15,6 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: '  sbx daemon restart'
 see_also:
    - sbx daemon - Manage sandboxd daemon
--- a/data/sbx_cli/sbx_daemon_start.yaml
+++ b/data/sbx_cli/sbx_daemon_start.yaml
@@ -22,5 +22,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx daemon start
+
+      # Run in the background
+      sbx daemon start --detach
 see_also:
    - sbx daemon - Manage sandboxd daemon
--- a/data/sbx_cli/sbx_daemon_status.yaml
+++ b/data/sbx_cli/sbx_daemon_status.yaml
@@ -1,14 +1,16 @@
 name: sbx daemon status
-synopsis: Check sandboxd daemon status
+synopsis: Show sandboxd daemon status
 usage: sbx daemon status [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
      usage: help for status
    - name: json
      default_value: "false"
-      usage: Output as JSON
+      usage: Output in JSON format
 inherited_options:
    - name: cloud
      default_value: "false"
@@ -18,5 +20,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx daemon status
+
+      # Machine-readable output
+      sbx daemon status --format json
 see_also:
    - sbx daemon - Manage sandboxd daemon
--- a/data/sbx_cli/sbx_daemon_stop.yaml
+++ b/data/sbx_cli/sbx_daemon_stop.yaml
@@ -15,5 +15,6 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: '  sbx daemon stop'
 see_also:
    - sbx daemon - Manage sandboxd daemon
--- a/data/sbx_cli/sbx_diagnose.yaml
+++ b/data/sbx_cli/sbx_diagnose.yaml
@@ -1,17 +1,16 @@
 name: sbx diagnose
 synopsis: Diagnose common issues with your sbx installation
-usage: sbx diagnose
+usage: sbx diagnose [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json, yaml or github-issue'
    - name: help
      shorthand: h
      default_value: "false"
      usage: help for diagnose
    - name: json
      default_value: "false"
-      usage: Output in JSON format (alias for --output json)
-    - name: output
-      shorthand: o
-      usage: 'Output format: "json" or "github-issue"'
+      usage: Output in JSON format
    - name: upload
      default_value: "false"
      usage: Upload diagnostics to Docker support
@@ -24,5 +23,13 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx diagnose
+
+      # Print the report as JSON
+      sbx diagnose --format json
+
+      # Upload the report to Docker support
+      sbx diagnose --upload
 see_also:
    - sbx - Manage AI coding agent sandboxes.
--- a/data/sbx_cli/sbx_env.yaml
+++ b/data/sbx_cli/sbx_env.yaml
@@ -100,49 +100,52 @@ description: |
    registrations, directories, published ports, the sandbox itself and the
    variables it runs with — is shown as a plan and approved before anything runs:

-      ── ENVIRONMENT PLAN
-         claude-proj
+      ENVIRONMENT
+        Name:   claude-proj
+        File:   /Users/me/proj/sbxenv.yaml

-         secrets:
-      +    anthropic:
-      +      ref: op://vault/anthropic/key
-      +      refresh: 55m
+      SECRETS
+        + anthropic
+            ref: op://vault/anthropic/key
+            refresh: 55m

-         lifecycle:
-           initialize:
-      ~      - command: make setup -> make setup && make seed
-               workdir: /Users/me/proj
+      LIFECYCLE
+        ~ initialize: make setup && make seed
+            command: make setup -> make setup && make seed
+            workdir: /Users/me/proj

-         Plan: + 1 to add, ~ 1 to change, - 0 to destroy.
+        1 to add · 1 to change · 0 to destroy

-         Approve this plan? [y/N]
+      Approve this plan? (y/N)

-    The plan is your file: the same keys, nested the same way, in the order the
-    blocks are declared in, so a line is looked up where it was written. What the
-    plan adds is the margin, and the two values a line moves between. The totals
-    name every symbol the margin can carry: "+ to add" and "~ to change" above,
+    The plan groups resources by the block of the file that declares them, in the
+    order the blocks are declared, so a row is looked up where it was written. The
+    mark in front of a row is what applying does to the resource, and the totals
+    name every mark a plan can carry: "+ to add" and "~ to change" above,
    "- to destroy" for what "sbx env rm" takes away, "> to run" for a command that
    runs again — a command converges to nothing, so it runs on every apply that
    reaches it — and "! to forget" for a resource this environment applied and no
-    longer declares. Where the file has nothing to
-    say, a note in the margin does: that a resource is missing, or that the work
-    waits for the next create, since a port, a credential, a kit or a postCreate
-    command comes with the sandbox, so attaching to one that already exists leaves it
-    for the next one that is built. A resource that is as it was, and already
-    approved, is left out: what is on screen is what there is to read.
+    longer declares. Where the file has nothing to say, the text after the row's name does:
+    that a resource is missing, or that the work waits for the next create, since a
+    port, a credential, a kit or a postCreate command comes with the sandbox, so
+    attaching to one that already exists leaves it for the next one that is built. A
+    resource that is as it was, and already approved, is left out: what is on screen
+    is what there is to read.

-    An attribute shows what the environment declares, so an edited kit argument or
-    variable reads as what it was against what it becomes, and a "command:" or "ref:"
-    secret shows where the credential comes from — a command that resolves one runs on
-    this machine. A secret's literal "value:" is the one exception: a plan is both shown
-    here and written to state, so it is named and stands in as a "sha256:" digest.
+    The lines under a row are the attributes the environment declares, so an edited
+    kit argument or variable reads as what it was against what it becomes, and a
+    "command:" or "ref:" secret shows where the credential comes from — a command
+    that resolves one runs on this machine. A secret's literal "value:" is the one
+    exception: a plan is both shown here and written to state, so it is named and
+    stands in as a "sha256:" digest.

-         kits:
-      ~    - source: ./mixins/tool
-      ~      args:
-      ~        version: 1.2.3 -> 1.2.4
-         env:
-      ~    GOFLAGS: -mod=mod -> -mod=readonly
+      KITS
+        ~ ./mixins/tool
+            args.version: 1.2.3 -> 1.2.4
+
+      ENV
+        ~ GOFLAGS
+            value: -mod=mod -> -mod=readonly

    What an attribute was is what this environment last applied here, or — for one it
    approved and never applied, such as a binding or a port answered for while
@@ -166,7 +169,7 @@ description: |
    runs rather than on the text approved before. "sbx env plan" prints the plan and
    changes nothing.

-    Use --auto-approve (-y) where there is no terminal to answer on. Where an
+    Use --force (-f) where there is no terminal to answer on. Where an
    environment's commands are your own and run many times a day,
    "sbx settings set env.rememberHostCommands true" asks about them only when
    they change.
@@ -214,7 +217,7 @@ description: |
    that process's existing environment.

      sbx --cloud env plan ./sbxenv.yaml
-      sbx --cloud env run --auto-approve --detached ./sbxenv.yaml
+      sbx --cloud env run --force --detach ./sbxenv.yaml
      sbx --cloud env exec ./sbxenv.yaml -- git status
      sbx --cloud env rm --force ./sbxenv.yaml
 usage: sbx env COMMAND
--- a/data/sbx_cli/sbx_env_create.yaml
+++ b/data/sbx_cli/sbx_env_create.yaml
@@ -32,10 +32,6 @@ description: |-
    than overriding, so an entry declared in both appears twice.
 usage: sbx env create [PATH...] [flags]
 options:
-    - name: auto-approve
-      shorthand: "y"
-      default_value: "false"
-      usage: Apply the environment plan without asking
    - name: clone
      default_value: "false"
      usage: |
@@ -50,6 +46,10 @@ options:
      experimental: true
      usage: |
        File of name=value environment arguments, one per line (can be repeated); --env-arg overrides
+    - name: force
+      shorthand: f
+      default_value: "false"
+      usage: Apply the environment plan without asking
    - name: help
      shorthand: h
      default_value: "false"
@@ -67,9 +67,15 @@ options:
    - name: name
      usage: |
        Name for the sandbox, overriding 'name:' in sbxenv.yaml and the derived <agent>-<directory> (every 'sbx env' command addressing this environment needs the same value)
+    - name: on-timeout
+      usage: |
+        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). Only applies when the sandbox is created; 'sbx --cloud env run' refuses it when attaching to an existing one.
    - name: skip-host-commands
      default_value: "false"
      usage: Skip the host lifecycle commands the environment declares
+    - name: ttl
+      usage: |
+        Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side). Only applies when the sandbox is created; 'sbx --cloud env run' refuses it when attaching to an existing one
 inherited_options:
    - name: cloud
      default_value: "false"
@@ -79,5 +85,11 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      # Create the environment described in the current directory
+      sbx env create
+
+      # Approve the plan without asking
+      sbx env create --force ./project
 see_also:
    - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file
--- a/data/sbx_cli/sbx_env_plan.yaml
+++ b/data/sbx_cli/sbx_env_plan.yaml
@@ -80,5 +80,8 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx env plan
+      sbx env plan ./project
 see_also:
    - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file
--- a/data/sbx_cli/sbx_env_rm.yaml
+++ b/data/sbx_cli/sbx_env_rm.yaml
@@ -70,5 +70,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx env rm
+
+      # Also remove the credential bindings the environment created
+      sbx env rm --force --prune-bindings ./project
 see_also:
    - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file
--- a/data/sbx_cli/sbx_env_run.yaml
+++ b/data/sbx_cli/sbx_env_run.yaml
@@ -33,15 +33,11 @@ description: |-
    than overriding, so an entry declared in both appears twice.
 usage: sbx env run [PATH...] [flags]
 options:
-    - name: auto-approve
-      shorthand: "y"
-      default_value: "false"
-      usage: Apply the environment plan without asking
    - name: clone
      default_value: "false"
      usage: |
        Override workspace.clone in sbxenv.yaml (see 'sbx create --clone')
-    - name: detached
+    - name: detach
      shorthand: d
      default_value: "false"
      usage: Create/start the sandbox without attaching
@@ -55,6 +51,10 @@ options:
      experimental: true
      usage: |
        File of name=value environment arguments, one per line (can be repeated); --env-arg overrides
+    - name: force
+      shorthand: f
+      default_value: "false"
+      usage: Apply the environment plan without asking
    - name: help
      shorthand: h
      default_value: "false"
@@ -72,9 +72,15 @@ options:
    - name: name
      usage: |
        Name for the sandbox, overriding 'name:' in sbxenv.yaml and the derived <agent>-<directory> (every 'sbx env' command addressing this environment needs the same value)
+    - name: on-timeout
+      usage: |
+        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). Only applies when the sandbox is created; 'sbx --cloud env run' refuses it when attaching to an existing one.
    - name: skip-host-commands
      default_value: "false"
      usage: Skip the host lifecycle commands the environment declares
+    - name: ttl
+      usage: |
+        Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side). Only applies when the sandbox is created; 'sbx --cloud env run' refuses it when attaching to an existing one
 inherited_options:
    - name: cloud
      default_value: "false"
@@ -84,5 +90,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx env run
+
+      # Start without attaching
+      sbx env run --detach ./project
 see_also:
    - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file
--- a/data/sbx_cli/sbx_kit.yaml
+++ b/data/sbx_cli/sbx_kit.yaml
@@ -26,7 +26,7 @@ see_also:
    - sbx - Manage AI coding agent sandboxes.
    - sbx kit add - Add a mixin to a sandbox
    - sbx kit builder - Manage the kit builder sandbox
-    - sbx kit inspect - Display details about a kit artifact
+    - sbx kit inspect - Show kit artifact details
    - sbx kit pack - Package a directory as a kit artifact
    - sbx kit provenance - Show the SLSA provenance attached to a kit
    - sbx kit pull - Pull a kit artifact from an OCI registry
--- a/data/sbx_cli/sbx_kit_builder.yaml
+++ b/data/sbx_cli/sbx_kit_builder.yaml
@@ -26,6 +26,6 @@ inherited_options:
      usage: Enable debug logging
 see_also:
    - sbx kit - (Experimental) Manage kit artifacts
-    - sbx kit builder history - Inspect kit build history in the builder sandbox
+    - sbx kit builder history - Show kit build history in the builder sandbox
    - sbx kit builder rm - Remove the kit builder sandbox and its build cache
    - sbx kit builder status - Show the kit builder sandbox and build-cache state
--- a/data/sbx_cli/sbx_kit_builder_history.yaml
+++ b/data/sbx_cli/sbx_kit_builder_history.yaml
@@ -1,5 +1,5 @@
 name: sbx kit builder history
-synopsis: Inspect kit build history in the builder sandbox
+synopsis: Show kit build history in the builder sandbox
 experimental: true
 description: |-
    Inspect kit build history in the builder sandbox.
@@ -25,8 +25,8 @@ inherited_options:
 see_also:
    - sbx kit builder - Manage the kit builder sandbox
    - sbx kit builder history export - Export a kit build record into a bundle
-    - sbx kit builder history inspect - Inspect a kit build record
-    - sbx kit builder history logs - Print a kit build's logs
+    - sbx kit builder history inspect - Show a kit build record
+    - sbx kit builder history logs - Show a kit build's logs
    - sbx kit builder history ls - List kit build records
    - sbx kit builder history rm - Remove kit build records
    - sbx kit builder history trace - Show the execution trace of a kit build
--- a/data/sbx_cli/sbx_kit_builder_history_export.yaml
+++ b/data/sbx_cli/sbx_kit_builder_history_export.yaml
@@ -16,5 +16,6 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: '  sbx kit builder history export 3b6l9x --output build.dockerbuild'
 see_also:
-    - sbx kit builder history - Inspect kit build history in the builder sandbox
+    - sbx kit builder history - Show kit build history in the builder sandbox
--- a/data/sbx_cli/sbx_kit_builder_history_inspect.yaml
+++ b/data/sbx_cli/sbx_kit_builder_history_inspect.yaml
@@ -1,5 +1,5 @@
 name: sbx kit builder history inspect
-synopsis: Inspect a kit build record
+synopsis: Show a kit build record
 experimental: true
 usage: sbx kit builder history inspect [ARGS...] [flags]
 options:
@@ -16,5 +16,11 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      # The most recent build
+      sbx kit builder history inspect
+
+      # One build by record reference
+      sbx kit builder history inspect 3b6l9x
 see_also:
-    - sbx kit builder history - Inspect kit build history in the builder sandbox
+    - sbx kit builder history - Show kit build history in the builder sandbox
--- a/data/sbx_cli/sbx_kit_builder_history_logs.yaml
+++ b/data/sbx_cli/sbx_kit_builder_history_logs.yaml
@@ -1,5 +1,5 @@
 name: sbx kit builder history logs
-synopsis: Print a kit build's logs
+synopsis: Show a kit build's logs
 experimental: true
 usage: sbx kit builder history logs [ARGS...] [flags]
 options:
@@ -16,5 +16,8 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx kit builder history logs
+      sbx kit builder history logs 3b6l9x
 see_also:
-    - sbx kit builder history - Inspect kit build history in the builder sandbox
+    - sbx kit builder history - Show kit build history in the builder sandbox
--- a/data/sbx_cli/sbx_kit_builder_history_ls.yaml
+++ b/data/sbx_cli/sbx_kit_builder_history_ls.yaml
@@ -16,5 +16,6 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: '  sbx kit builder history ls'
 see_also:
-    - sbx kit builder history - Inspect kit build history in the builder sandbox
+    - sbx kit builder history - Show kit build history in the builder sandbox
--- a/data/sbx_cli/sbx_kit_builder_history_rm.yaml
+++ b/data/sbx_cli/sbx_kit_builder_history_rm.yaml
@@ -21,5 +21,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx kit builder history rm 3b6l9x
+
+      # Skip the confirmation prompt
+      sbx kit builder history rm --yes 3b6l9x
 see_also:
-    - sbx kit builder history - Inspect kit build history in the builder sandbox
+    - sbx kit builder history - Show kit build history in the builder sandbox
--- a/data/sbx_cli/sbx_kit_builder_history_trace.yaml
+++ b/data/sbx_cli/sbx_kit_builder_history_trace.yaml
@@ -16,5 +16,8 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx kit builder history trace
+      sbx kit builder history trace 3b6l9x
 see_also:
-    - sbx kit builder history - Inspect kit build history in the builder sandbox
+    - sbx kit builder history - Show kit build history in the builder sandbox
--- a/data/sbx_cli/sbx_kit_builder_rm.yaml
+++ b/data/sbx_cli/sbx_kit_builder_rm.yaml
@@ -20,5 +20,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx kit builder rm
+
+      # Skip the confirmation prompt
+      sbx kit builder rm --force
 see_also:
    - sbx kit builder - Manage the kit builder sandbox
--- a/data/sbx_cli/sbx_kit_builder_status.yaml
+++ b/data/sbx_cli/sbx_kit_builder_status.yaml
@@ -16,5 +16,6 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: '  sbx kit builder status'
 see_also:
    - sbx kit builder - Manage the kit builder sandbox
--- a/data/sbx_cli/sbx_kit_inspect.yaml
+++ b/data/sbx_cli/sbx_kit_inspect.yaml
@@ -1,5 +1,5 @@
 name: sbx kit inspect
-synopsis: Display details about a kit artifact
+synopsis: Show kit artifact details
 experimental: true
 description: |-
    Load and display details about a kit artifact.
@@ -10,6 +10,8 @@ description: |-
    arguments; the output shows the substituted content.
 usage: sbx kit inspect REFERENCE [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
@@ -36,5 +38,11 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx kit inspect ./my-kit
+      sbx kit inspect ghcr.io/myorg/my-kit:1.0
+
+      # Machine-readable output
+      sbx kit inspect ghcr.io/myorg/my-kit:1.0 --format json
 see_also:
    - sbx kit - (Experimental) Manage kit artifacts
--- a/data/sbx_cli/sbx_kit_pack.yaml
+++ b/data/sbx_cli/sbx_kit_pack.yaml
@@ -13,7 +13,7 @@ options:
      usage: help for pack
    - name: output
      shorthand: o
-      usage: 'Output ZIP file path (default: <name>.zip)'
+      usage: 'Output file path; must end in .zip (default: <name>.zip)'
 inherited_options:
    - name: cloud
      default_value: "false"
@@ -23,5 +23,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx kit pack ./my-kit
+
+      # Choose the archive name
+      sbx kit pack ./my-kit --output dist/my-kit.zip
 see_also:
    - sbx kit - (Experimental) Manage kit artifacts
--- a/data/sbx_cli/sbx_kit_provenance.yaml
+++ b/data/sbx_cli/sbx_kit_provenance.yaml
@@ -25,6 +25,8 @@ options:
      usage: Exact keyless OIDC issuer
    - name: certificate-oidc-issuer-regexp
      usage: Keyless OIDC issuer regexp
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
--- a/data/sbx_cli/sbx_kit_pull.yaml
+++ b/data/sbx_cli/sbx_kit_pull.yaml
@@ -32,5 +32,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx kit pull ghcr.io/myorg/my-kit:1.0
+
+      # Choose where to save the payload
+      sbx kit pull ghcr.io/myorg/my-kit:1.0 --output my-kit.tar.gz
 see_also:
    - sbx kit - (Experimental) Manage kit artifacts
--- a/data/sbx_cli/sbx_kit_push.yaml
+++ b/data/sbx_cli/sbx_kit_push.yaml
@@ -59,5 +59,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx kit push ./my-kit ghcr.io/myorg/my-kit:1.0
+
+      # Sign the pushed kit (keyless)
+      sbx kit push ./my-kit ghcr.io/myorg/my-kit:1.0 --sign
 see_also:
    - sbx kit - (Experimental) Manage kit artifacts
--- a/data/sbx_cli/sbx_kit_validate.yaml
+++ b/data/sbx_cli/sbx_kit_validate.yaml
@@ -11,6 +11,8 @@ description: |-
    create.
 usage: sbx kit validate REFERENCE [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
@@ -37,5 +39,11 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx kit validate ./my-kit
+      sbx kit validate ./my-kit.zip
+
+      # Supply the arguments a kit declares
+      sbx kit validate ./my-kit --kit-arg region=eu
 see_also:
    - sbx kit - (Experimental) Manage kit artifacts
--- a/data/sbx_cli/sbx_kit_verify.yaml
+++ b/data/sbx_cli/sbx_kit_verify.yaml
@@ -29,6 +29,8 @@ options:
      usage: Exact keyless OIDC issuer
    - name: certificate-oidc-issuer-regexp
      usage: Keyless OIDC issuer regexp
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
--- a/data/sbx_cli/sbx_login.yaml
+++ b/data/sbx_cli/sbx_login.yaml
@@ -20,5 +20,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx login
+
+      # Non-interactive sign-in, for CI
+      echo "$DOCKER_PAT" | sbx login --username me --password-stdin
 see_also:
    - sbx - Manage AI coding agent sandboxes.
--- a/data/sbx_cli/sbx_logout.yaml
+++ b/data/sbx_cli/sbx_logout.yaml
@@ -2,14 +2,14 @@ name: sbx logout
 synopsis: Stop running local sandboxes and sign out of Docker
 usage: sbx logout [flags]
 options:
+    - name: force
+      shorthand: f
+      default_value: "false"
+      usage: Skip confirmation prompt
    - name: help
      shorthand: h
      default_value: "false"
      usage: help for logout
-    - name: "yes"
-      shorthand: "y"
-      default_value: "false"
-      usage: Skip confirmation prompt
 inherited_options:
    - name: cloud
      default_value: "false"
@@ -19,5 +19,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx logout
+
+      # Skip the confirmation prompt
+      sbx logout --force
 see_also:
    - sbx - Manage AI coding agent sandboxes.
--- a/data/sbx_cli/sbx_ls.yaml
+++ b/data/sbx_cli/sbx_ls.yaml
@@ -4,6 +4,8 @@ description: |
    List all sandboxes with their agent, status, published ports, and workspace.
 usage: sbx ls [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
@@ -24,5 +26,13 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx ls
+
+      # Names only, for scripting
+      sbx ls -q
+
+      # Machine-readable output
+      sbx ls --format json
 see_also:
    - sbx - Manage AI coding agent sandboxes.
--- a/data/sbx_cli/sbx_mcp.yaml
+++ b/data/sbx_cli/sbx_mcp.yaml
@@ -25,3 +25,4 @@ see_also:
    - sbx mcp load - Load an already-registered MCP server into a running sandbox
    - sbx mcp ls - List MCP servers
    - sbx mcp rm - Remove a registered MCP server
+    - sbx mcp unload - Unload an MCP server from a running sandbox
--- a/data/sbx_cli/sbx_mcp_add.yaml
+++ b/data/sbx_cli/sbx_mcp_add.yaml
@@ -215,7 +215,7 @@ description: |-
      process runs with your host user's full permissions — it can read
      your filesystem, access your network, and call any API your user
      can. Do not use --command with untrusted executables.
-usage: sbx mcp add <name> (--url <url> | --command <cmd>) [flags]
+usage: sbx mcp add NAME (--url URL | --command COMMAND) [flags]
 options:
    - name: args
      default_value: '[]'
--- a/data/sbx_cli/sbx_mcp_auth.yaml
+++ b/data/sbx_cli/sbx_mcp_auth.yaml
@@ -48,7 +48,7 @@ description: |-

    Scope values may be URN-shaped (urn:ietf:params:oauth:scope:mail) or URL-shaped
    (https://www.fastmail.com/dev/mcp); neither needs quoting.
-usage: sbx mcp auth [server-name] [flags]
+usage: sbx mcp auth [SERVER] [flags]
 options:
    - name: all
      default_value: "false"
@@ -62,7 +62,7 @@ options:
      usage: help for auth
    - name: json
      default_value: "false"
-      usage: Output in JSON format (alias for --format json)
+      usage: Output in JSON format
    - name: no-scope
      default_value: "false"
      usage: |
--- a/data/sbx_cli/sbx_mcp_auth_rm.yaml
+++ b/data/sbx_cli/sbx_mcp_auth_rm.yaml
@@ -5,7 +5,7 @@ description: |-

    This command does not remove local MCP server registrations. Use 'sbx mcp rm'
    to remove a registration.
-usage: sbx mcp auth rm [server-name] [flags]
+usage: sbx mcp auth rm [SERVER] [flags]
 options:
    - name: all
      default_value: "false"
@@ -23,7 +23,7 @@ options:
      usage: help for rm
    - name: json
      default_value: "false"
-      usage: Output in JSON format (alias for --format json)
+      usage: Output in JSON format
 inherited_options:
    - name: cloud
      default_value: "false"
--- a/data/sbx_cli/sbx_mcp_auth_status.yaml
+++ b/data/sbx_cli/sbx_mcp_auth_status.yaml
@@ -4,7 +4,7 @@ description: |-
    Show hosted OAuth credential status for registered MCP servers.

    This command does not start OAuth or refresh expired credentials.
-usage: sbx mcp auth status [server-name] [flags]
+usage: sbx mcp auth status [SERVER] [flags]
 options:
    - name: all
      default_value: "false"
@@ -18,7 +18,7 @@ options:
      usage: help for status
    - name: json
      default_value: "false"
-      usage: Output in JSON format (alias for --format json)
+      usage: Output in JSON format
 inherited_options:
    - name: cloud
      default_value: "false"
--- a/data/sbx_cli/sbx_mcp_inspect.yaml
+++ b/data/sbx_cli/sbx_mcp_inspect.yaml
@@ -1,7 +1,9 @@
 name: sbx mcp inspect
 synopsis: Show MCP server details
-usage: sbx mcp inspect <name> [flags]
+usage: sbx mcp inspect NAME [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
--- a/data/sbx_cli/sbx_mcp_load.yaml
+++ b/data/sbx_cli/sbx_mcp_load.yaml
@@ -14,7 +14,7 @@ description: |-
    There is no local registration: the cloud gateway resolves the server name
    itself, and the sandbox may be given by name or sbx_ ID. Connected agents see
    the new server's tools immediately.
-usage: sbx mcp load <name> --sandbox <sandbox> [flags]
+usage: sbx mcp load NAME --sandbox SANDBOX [flags]
 options:
    - name: help
      shorthand: h
--- a/data/sbx_cli/sbx_mcp_ls.yaml
+++ b/data/sbx_cli/sbx_mcp_ls.yaml
@@ -26,6 +26,8 @@ description: |-
    skipped servers.
 usage: sbx mcp ls [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
--- a/data/sbx_cli/sbx_mcp_rm.yaml
+++ b/data/sbx_cli/sbx_mcp_rm.yaml
@@ -1,6 +1,6 @@
 name: sbx mcp rm
 synopsis: Remove a registered MCP server
-usage: sbx mcp rm <name> [flags]
+usage: sbx mcp rm NAME [flags]
 options:
    - name: force
      shorthand: f
--- a/data/sbx_cli/sbx_mcp_unload.yaml
+++ b/data/sbx_cli/sbx_mcp_unload.yaml
@@ -0,0 +1,32 @@
+name: sbx mcp unload
+synopsis: Unload an MCP server from a running sandbox
+description: |-
+    Detach an MCP server from a running sandbox's gateway.
+    Connected agents stop seeing the server's tools immediately via the standard
+    MCP tools/list_changed notification — no agent restart required. The server
+    is not restored when the sandbox is restarted.
+
+    The server stays registered in the local MCP store; load it again with
+    'sbx mcp load', or remove the registration with 'sbx mcp rm'.
+usage: sbx mcp unload NAME --sandbox SANDBOX [flags]
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for unload
+    - name: sandbox
+      usage: Target sandbox name (required)
+inherited_options:
+    - name: cloud
+      default_value: "false"
+      usage: |
+        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+example: |4-
+      # Unload the 'notion' server from the running sandbox 'my-sbx'.
+      sbx mcp unload notion --sandbox my-sbx
+see_also:
+    - sbx mcp - Manage MCP servers
--- a/data/sbx_cli/sbx_move.yaml
+++ b/data/sbx_cli/sbx_move.yaml
@@ -57,7 +57,8 @@ description: |-

    The cloud sandbox a move creates expires. The default is the server's TTL,
    typically 1h: stopped in place on expiry when the account and sandbox
-    support it, deleted otherwise. Choose with --ttl and --on-timeout.
+    support it, deleted otherwise. Choose with --ttl and --on-timeout;
+    '--on-timeout restart' keeps the destination running instead of expiring.
    Extend later with 'sbx --cloud ttl'.
 usage: sbx move SANDBOX [flags]
 options:
@@ -74,7 +75,7 @@ options:
        Name for the destination sandbox (default: 'moved-' + the source name; a cloud destination always adds a short unique suffix, a local one only when that name is already taken)
    - name: on-timeout
      usage: |
-        What happens to the destination cloud sandbox when its TTL lapses: 'stop' stops it in place so it can be started again later, or 'delete' removes it. Not every sandbox supports 'stop', and an explicit request the server refuses fails the move. Default: stop when the sandbox supports it, else the server default (delete). Only with --to cloud
+        What happens to the destination cloud sandbox when its TTL lapses: 'stop' stops it in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Not every sandbox supports 'stop', and an explicit request the server refuses fails the move after the source has been stopped and uploaded, so the sandbox is restored but the transfer is spent. With 'restart' a supplied --ttl must be at least 1h. Default: stop when the sandbox supports it, else the server default (delete). Only with --to cloud
    - name: to
      usage: |
        Destination of the move: 'local' (cloud to local) or 'cloud' (local to cloud)
--- a/data/sbx_cli/sbx_policy.yaml
+++ b/data/sbx_cli/sbx_policy.yaml
@@ -27,7 +27,7 @@ see_also:
    - sbx policy check - Check whether policy allows an access request
    - sbx policy deny - Add a deny rule for sandboxes
    - sbx policy init - Initialize the global network policy
-    - sbx policy inspect - Inspect policy or rule details
+    - sbx policy inspect - Show policy or rule details
    - sbx policy log - Show sandbox policy logs
    - sbx policy ls - List sandbox policies
    - sbx policy reset - Reset policies to defaults
--- a/data/sbx_cli/sbx_policy_check_network.yaml
+++ b/data/sbx_cli/sbx_policy_check_network.yaml
@@ -9,6 +9,8 @@ description: |-
    and port: this command evaluates network authorization, not HTTP method or path.
 usage: sbx policy check network [--sandbox SANDBOX] TARGET [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
--- a/data/sbx_cli/sbx_policy_init.yaml
+++ b/data/sbx_cli/sbx_policy_init.yaml
@@ -26,7 +26,7 @@ description: |-
    one sandbox with --sandbox, keeps the existing allow and deny rules, and can be
    run again. balanced is deny-all plus the balanced allow list added to the scope.
    Use "sbx --cloud policy reset" to clear the rules first.
-usage: sbx policy init <allow-all|balanced|deny-all> [flags]
+usage: sbx policy init allow-all|balanced|deny-all [flags]
 options:
    - name: help
      shorthand: h
--- a/data/sbx_cli/sbx_policy_inspect.yaml
+++ b/data/sbx_cli/sbx_policy_inspect.yaml
@@ -1,5 +1,5 @@
 name: sbx policy inspect
-synopsis: Inspect policy or rule details
+synopsis: Show policy or rule details
 description: |-
    Inspect full detail for a selected policy or rule.

@@ -11,8 +11,10 @@ description: |-
    identifier accepted by "sbx policy rm network --id" (local rules only). Use
    "sbx policy ls" to find policy names and "sbx policy ls --wide" to find rule
    IDs and resource values.
-usage: sbx policy inspect <policy-or-rule> [flags]
+usage: sbx policy inspect POLICY|RULE [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
--- a/data/sbx_cli/sbx_policy_log.yaml
+++ b/data/sbx_cli/sbx_policy_log.yaml
@@ -8,6 +8,8 @@ description: |-
    issues or auditing network activity.
 usage: sbx policy log [SANDBOX] [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
@@ -18,10 +20,6 @@ options:
    - name: limit
      default_value: "0"
      usage: Maximum number of log entries to show
-    - name: quiet
-      shorthand: q
-      default_value: "false"
-      usage: Only display log entries
    - name: type
      default_value: all
      usage: |
--- a/data/sbx_cli/sbx_policy_ls.yaml
+++ b/data/sbx_cli/sbx_policy_ls.yaml
@@ -23,6 +23,8 @@ options:
        Filter policies by how they were created: "default", "added", "provisioned", or "approval"
    - name: decision
      usage: 'Filter policies by decision: "allow" or "deny"'
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
@@ -32,7 +34,7 @@ options:
      usage: Show inactive policy rules hidden by remote governance
    - name: json
      default_value: "false"
-      usage: Output filtered policy rules as JSON
+      usage: Output in JSON format
    - name: protocol
      usage: 'Filter network rules by protocol: tcp or udp'
    - name: source
--- a/data/sbx_cli/sbx_ports.yaml
+++ b/data/sbx_cli/sbx_ports.yaml
@@ -35,13 +35,15 @@ description: |-
    for each exposed port.
 usage: sbx ports SANDBOX [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
      usage: help for ports
    - name: json
      default_value: "false"
-      usage: Output in JSON format (for port listing)
+      usage: Output in JSON format
    - name: publish
      default_value: '[]'
      usage: |
--- a/data/sbx_cli/sbx_prune.yaml
+++ b/data/sbx_cli/sbx_prune.yaml
@@ -15,7 +15,7 @@ description: |-
    it has been stopped cannot be established.

    Use --dry-run to list what would be removed without removing anything, and
-    --json with it for machine-readable output.
+    --format json or --format yaml with it for machine-readable output.

    Pruning requires confirmation; use --force to skip the confirmation prompt
    (for non-interactive scripts) and to remove a sandbox that is in use (e.g. an
@@ -39,13 +39,15 @@ options:
      default_value: "false"
      usage: |
        Skip confirmation prompts and remove even if in use (e.g. an open SSH connection)
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
      usage: help for prune
    - name: json
      default_value: "false"
-      usage: Output the --dry-run listing in JSON format
+      usage: Output in JSON format
 inherited_options:
    - name: cloud
      default_value: "false"
@@ -55,5 +57,14 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      # Show what would be removed
+      sbx prune --dry-run
+
+      # Remove without asking
+      sbx prune --force
+
+      # Only sandboxes stopped before a point in time
+      sbx prune --filter until=2026-01-01T00:00:00Z
 see_also:
    - sbx - Manage AI coding agent sandboxes.
--- a/data/sbx_cli/sbx_reset.yaml
+++ b/data/sbx_cli/sbx_reset.yaml
@@ -46,5 +46,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx reset
+
+      # Skip the confirmation prompt and keep stored secrets
+      sbx reset --force --preserve-secrets
 see_also:
    - sbx - Manage AI coding agent sandboxes.
--- a/data/sbx_cli/sbx_rm.yaml
+++ b/data/sbx_cli/sbx_rm.yaml
@@ -28,10 +28,15 @@ options:
      default_value: "false"
      usage: |
        Skip confirmation prompts and delete even if in use (e.g. an open SSH connection)
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
      usage: help for rm
+    - name: json
+      default_value: "false"
+      usage: Output in JSON format
 inherited_options:
    - name: cloud
      default_value: "false"
@@ -41,5 +46,13 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx rm my-sandbox
+
+      # Remove several at once
+      sbx rm one two
+
+      # Remove every sandbox without asking
+      sbx rm --all --force
 see_also:
    - sbx - Manage AI coding agent sandboxes.
--- a/data/sbx_cli/sbx_run.yaml
+++ b/data/sbx_cli/sbx_run.yaml
@@ -20,7 +20,7 @@ description: |-
    workspace.

    To create a sandbox without attaching, use "sbx create" instead, or
-    pass --detached (-d) to print the sandbox ID and exit without opening an
+    pass --detach (-d) to print the sandbox ID and exit without opening an
    interactive session.

    Available agents: claude, codex, copilot, cursor, devin, docker-agent, droid, gemini, kiro, opencode, shell
@@ -37,11 +37,11 @@ description: |-
    Running an agent that has existing sandboxes, running or stopped, prompts you
    to pick one to reuse or to create a new one. Pass --new to skip the prompt and
    always create a fresh sandbox. --name NAME reuses and restarts the sandbox of
-    that name when it exists and creates it otherwise. A launch that bakes a kit
-    template (a sandbox kit or a mixin with build content) always creates fresh.
-    --detached skips the prompt: with --name it restarts that sandbox when it
+    that name when it exists and creates it otherwise. A sandbox kit launch always
+    creates fresh, as does a launch that bakes a mixin with build content.
+    --detach skips the prompt: with --name it restarts that sandbox when it
    exists, otherwise it creates a new one. A non-interactive run without
-    --detached is refused, so scripts pass --detached (e.g.
+    --detach is refused, so scripts pass --detach (e.g.
    sbx --cloud run -d claude && sbx --cloud exec ...).

    Sizing comes from --cpus and --memory and must land on a billable shape; without
@@ -64,14 +64,14 @@ options:
    - name: deny-network
      usage: |
        Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with 'sbx policy ls <NAME>' or 'sbx policy rm network --sandbox <NAME> --resource <HOST>'. Safe under centralized governance because a local deny can only narrow, never widen, egress.
-    - name: detach-keys
-      usage: |
-        Override the detach gesture that leaves the session running (Docker-style, e.g. "ctrl-\", "ctrl-x,ctrl-d"). Default: Ctrl-\. Use this when the default collides with an agent's keymap (cloud only).
-    - name: detached
+    - name: detach
      shorthand: d
      default_value: "false"
      usage: |
        Start the sandbox and print its ID without opening an agent session
+    - name: detach-keys
+      usage: |
+        Override the detach gesture that leaves the session running (Docker-style, e.g. "ctrl-\", "ctrl-x,ctrl-d"). Default: Ctrl-\. Use this when the default collides with an agent's keymap (cloud only).
    - name: env
      shorthand: e
      default_value: '[]'
@@ -122,8 +122,8 @@ options:
      usage: |
        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]. Applied when the sandbox is created; ignored when re-attaching (use "sbx ports")
    - name: pull
-      default_value: always
-      usage: Image pull policy (always|missing|never)
+      usage: |
+        Image pull policy (always|missing|never; default: never for saved local snapshots, missing for v3 kit compositions, otherwise always)
    - name: rm
      default_value: "false"
      usage: Remove the sandbox after the agent session exits
@@ -185,7 +185,7 @@ example: |4-
      sbx --cloud run claude

      # Create a cloud sandbox non-interactively and print its ID
-      sbx --cloud run --detached claude
+      sbx --cloud run --detach claude

      # Reuse the cloud sandbox of that name, creating it when it does not exist
      sbx --cloud run --name my-project claude
--- a/data/sbx_cli/sbx_secret_ls.yaml
+++ b/data/sbx_cli/sbx_secret_ls.yaml
@@ -7,6 +7,8 @@ description: |-
    global secrets, or --sandbox to show only secrets scoped to one sandbox.
 usage: sbx secret ls [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: global
      shorthand: g
      default_value: "false"
--- a/data/sbx_cli/sbx_settings.yaml
+++ b/data/sbx_cli/sbx_settings.yaml
@@ -27,6 +27,6 @@ inherited_options:
 see_also:
    - sbx - Manage AI coding agent sandboxes.
    - sbx settings get - Get the value of a setting
-    - sbx settings list - List settings
+    - sbx settings ls - List settings
    - sbx settings set - Set a setting override
    - sbx settings unset - Remove a setting override
--- a/data/sbx_cli/sbx_settings_get.yaml
+++ b/data/sbx_cli/sbx_settings_get.yaml
@@ -5,15 +5,17 @@ description: |-

    Use --json to print the complete setting record, including its source, type,
    default, and description.
-usage: sbx settings get <key> [flags]
+usage: sbx settings get KEY [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
      usage: help for get
    - name: json
      default_value: "false"
-      usage: Print the complete setting record as JSON
+      usage: Output in JSON format
 inherited_options:
    - name: cloud
      default_value: "false"
--- a/data/sbx_cli/sbx_settings_list.yaml
+++ b/data/sbx_cli/sbx_settings_list.yaml
@@ -1,4 +1,4 @@
-name: sbx settings list
+name: sbx settings ls
 synopsis: List settings
 description: |-
    List known settings with their evaluated value, type, source, and description.
@@ -6,17 +6,19 @@ description: |-
    The SOURCE column shows where the value came from (default, envvar, or
    override). RESTART identifies settings that require 'sbx daemon restart' for
    existing daemon-side consumers. Long values and descriptions are truncated to
-    keep the table readable; use --no-trunc or --json for complete output. Use
-    'sbx settings get <key>' to print one value in full.
-usage: sbx settings list [flags]
+    keep the table readable; use --no-trunc or --format json for complete output. Use
+    'sbx settings get KEY' to print one value in full.
+usage: sbx settings ls [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
-      usage: help for list
+      usage: help for ls
    - name: json
      default_value: "false"
-      usage: Print complete setting records as JSON
+      usage: Output in JSON format
    - name: no-trunc
      default_value: "false"
      usage: Show full values and descriptions, one setting per block
@@ -31,9 +33,9 @@ inherited_options:
      usage: Enable debug logging
 example: |4-
      # List settings as a table
-      sbx settings list
+      sbx settings ls

      # List settings as JSON
-      sbx settings list --json
+      sbx settings ls --format json
 see_also:
    - sbx settings - Manage Docker Sandboxes settings
--- a/data/sbx_cli/sbx_settings_set.yaml
+++ b/data/sbx_cli/sbx_settings_set.yaml
@@ -16,7 +16,7 @@ description: |-

    Most changes take effect within about five seconds. If a daemon restart is
    required, this command tells you to run 'sbx daemon restart'.
-usage: sbx settings set <key> <value> [flags]
+usage: sbx settings set KEY VALUE [flags]
 options:
    - name: help
      shorthand: h
--- a/data/sbx_cli/sbx_settings_unset.yaml
+++ b/data/sbx_cli/sbx_settings_unset.yaml
@@ -5,7 +5,7 @@ description: |-

    Administrator policy remains in effect. Otherwise, the setting evaluates from
    its environment variable, remote default, or built-in default.
-usage: sbx settings unset <key> [flags]
+usage: sbx settings unset KEY [flags]
 options:
    - name: help
      shorthand: h
--- a/data/sbx_cli/sbx_setup.yaml
+++ b/data/sbx_cli/sbx_setup.yaml
@@ -7,9 +7,9 @@ description: |-

    Agent secrets are detected from the built-in agent kit specs and the
    env vars set on this host, and accepted secrets are imported into the global
-    secrets store (the same store as "sbx secret set"). When SSH_AUTH_SOCK is set,
-    setup can enable SSH-agent forwarding and either use each client's current
-    socket or persist a fixed socket path.
+    secrets store (the same store as "sbx secret set"). Setup can enable SSH-agent
+    forwarding using each client's SSH_AUTH_SOCK, or the native Windows OpenSSH
+    agent pipe when that variable is unset. A fixed endpoint can also be configured.
 usage: sbx setup [COMMAND]
 options:
    - name: help
--- a/data/sbx_cli/sbx_setup_ssh.yaml
+++ b/data/sbx_cli/sbx_setup_ssh.yaml
@@ -6,14 +6,19 @@ description: |-
    ~/.ssh/config so "ssh <name>.sbx" connects with no prompts. Named app instances
    use "ssh <name>.sbx-<app>" instead. Re-run any time; it's idempotent.

-    No SSH client key is needed — authentication is handled by the daemon's Unix
-    socket (OS user boundary) combined with an active Docker login. Sign in first
-    (sbx login).
+    No SSH client key is needed — authentication is handled by the daemon's local
+    socket or named pipe (OS user boundary) combined with an active Docker login. Sign in first
+    (sbx login). On macOS and Windows, use --auto-create to install the fixed codex.sbx and
+    claude.sbx desktop profiles. Sandboxes are created with the standard resource defaults.
 usage: sbx setup ssh [flags]
 options:
    - name: alias
      default_value: '*.sbx'
      usage: ssh_config Host pattern to write
+    - name: auto-create
+      default_value: "false"
+      usage: |
+        enable managed Codex and Claude Desktop profiles on macOS and Windows
    - name: help
      shorthand: h
      default_value: "false"
@@ -32,4 +37,4 @@ example: |4-
      ssh my-sandbox.sbx -- echo hello
 see_also:
    - sbx setup - (Experimental) Detect host configuration and prepare Docker Sandboxes
-    - sbx setup ssh remove - Remove SSH client config for the current local app instance
+    - sbx setup ssh remove - Remove SSH config and desktop targets; keep sandboxes
--- a/data/sbx_cli/sbx_setup_ssh_remove.yaml
+++ b/data/sbx_cli/sbx_setup_ssh_remove.yaml
@@ -1,5 +1,5 @@
 name: sbx setup ssh remove
-synopsis: Remove SSH client config for the current local app instance
+synopsis: Remove SSH config and desktop targets; keep sandboxes
 experimental: true
 usage: sbx setup ssh remove [flags]
 options:
@@ -16,5 +16,6 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: '  sbx setup ssh remove'
 see_also:
    - sbx setup ssh - Set up SSH client config for the sandbox endpoint
--- a/data/sbx_cli/sbx_skills_add.yaml
+++ b/data/sbx_cli/sbx_skills_add.yaml
@@ -13,7 +13,7 @@ description: |-
    The repository can be specified as a Git URL or as GitHub owner/repository
    shorthand. Skills installed with this command can later be refreshed with
    'sbx skills update'.
-usage: sbx skills add <repository> [flags]
+usage: sbx skills add REPOSITORY [flags]
 options:
    - name: force
      shorthand: f
--- a/data/sbx_cli/sbx_skills_import.yaml
+++ b/data/sbx_cli/sbx_skills_import.yaml
@@ -48,5 +48,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx skills import
+
+      # Preview without changing anything
+      sbx skills import --dry-run
 see_also:
    - sbx skills - (Experimental) Manage skills available in sandboxes
--- a/data/sbx_cli/sbx_skills_ls.yaml
+++ b/data/sbx_cli/sbx_skills_ls.yaml
@@ -4,6 +4,8 @@ experimental: true
 description: List skills available to agents in Docker Sandboxes.
 usage: sbx skills ls [flags]
 options:
+    - name: format
+      usage: 'Output format: table, json or yaml'
    - name: help
      shorthand: h
      default_value: "false"
@@ -24,5 +26,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx skills ls
+
+      # Machine-readable output
+      sbx skills ls --format json
 see_also:
    - sbx skills - (Experimental) Manage skills available in sandboxes
--- a/data/sbx_cli/sbx_skills_rm.yaml
+++ b/data/sbx_cli/sbx_skills_rm.yaml
@@ -6,7 +6,7 @@ description: |-

    Running agents may be reading installed skills. Removal cannot be undone and
    requires confirmation; use --force to skip confirmation in scripts.
-usage: sbx skills rm <skill>... [flags]
+usage: sbx skills rm SKILL... [flags]
 options:
    - name: force
      shorthand: f
@@ -25,5 +25,10 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      sbx skills rm my-skill
+
+      # Skip the confirmation prompt
+      sbx skills rm --force my-skill
 see_also:
    - sbx skills - (Experimental) Manage skills available in sandboxes
--- a/data/sbx_cli/sbx_skills_update.yaml
+++ b/data/sbx_cli/sbx_skills_update.yaml
@@ -7,7 +7,7 @@ description: |-
    With no names, every skill added from a repository is updated. Specify one or
    more names to update only those skills. Skills installed with 'sbx skills
    import' must be added from a repository before they can be updated.
-usage: sbx skills update [skill]... [flags]
+usage: sbx skills update [SKILL...] [flags]
 options:
    - name: help
      shorthand: h
@@ -22,5 +22,11 @@ inherited_options:
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
+example: |4-
+      # Update every skill added from a repository
+      sbx skills update
+
+      # Update one skill
+      sbx skills update my-skill
 see_also:
    - sbx skills - (Experimental) Manage skills available in sandboxes
--- a/Show More
+++ b/Show More