Merge pull request #25102 from dvdksn/dvdksn/sbx-cli-reference-updates

Update sbx CLI reference data

data/sbx_cli/sbx.yaml

@@ -20,6 +20,7 @@ see_also:
     - sbx create - Create a sandbox for an agent
     - sbx diagnose - Diagnose common issues with your sbx installation
     - sbx exec - Execute a command inside a sandbox
+    - sbx kit - Manage kit artifacts
     - sbx login - Sign in to Docker
     - sbx logout - Sign out of Docker
     - sbx ls - List sandboxes

data/sbx_cli/sbx_kit.yaml

@@ -0,0 +1,26 @@
+name: sbx kit
+synopsis: Manage kit artifacts
+description: |-
+    Manage kit artifacts.
+
+    Kits are declarative YAML artifacts that extend sandbox agents with additional
+    credentials, network policies, environment variables, startup commands, and files.
+usage: sbx kit COMMAND
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for kit
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+see_also:
+    - sbx - Manage AI coding agent sandboxes.
+    - sbx kit add - Add a kit to a running sandbox
+    - sbx kit inspect - Display details about a kit artifact
+    - sbx kit pack - Package a directory as a kit artifact
+    - sbx kit pull - Pull a kit artifact from an OCI registry
+    - sbx kit push - Push a kit artifact to an OCI registry
+    - sbx kit validate - Validate a kit artifact

data/sbx_cli/sbx_kit_add.yaml

@@ -0,0 +1,35 @@
+name: sbx kit add
+synopsis: Add a kit to a running sandbox
+description: |-
+    Inject a kit artifact into an already-running sandbox.
+
+    The kit's files, init files, and startup commands are applied to the
+    running container. This allows extending a sandbox without recreating it.
+
+    The sandbox must already exist (created or running). The reference can be a local directory,
+    ZIP file path, OCI registry reference, or git repository.
+usage: sbx kit add SANDBOX REFERENCE [flags]
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for add
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+example: |4-
+      # Add a local kit directory to a sandbox
+      sbx kit add my-sandbox ./mcp-postgres/
+
+      # Add a kit from a ZIP file
+      sbx kit add my-sandbox ./mcp-postgres.zip
+
+      # Add a kit from an OCI registry
+      sbx kit add my-sandbox ghcr.io/myorg/mcp-postgres:1.0
+
+      # Add a kit from a git repository
+      sbx kit add my-sandbox git+https://github.com/org/kits.git#dir=mcp-postgres
+see_also:
+    - sbx kit - Manage kit artifacts

data/sbx_cli/sbx_kit_inspect.yaml

@@ -0,0 +1,22 @@
+name: sbx kit inspect
+synopsis: Display details about a kit artifact
+description: |-
+    Load and display details about a kit artifact.
+
+    The reference can be a local directory, ZIP file path, OCI registry reference, or git repository.
+usage: sbx kit inspect REFERENCE [flags]
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for inspect
+    - name: json
+      default_value: "false"
+      usage: Output in JSON format
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+see_also:
+    - sbx kit - Manage kit artifacts

data/sbx_cli/sbx_kit_pack.yaml

@@ -0,0 +1,22 @@
+name: sbx kit pack
+synopsis: Package a directory as a kit artifact
+description: |-
+    Validate and package a kit artifact directory as a ZIP file.
+
+    The directory must contain a valid spec.yaml and an optional files/ directory.
+usage: sbx kit pack DIRECTORY [flags]
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for pack
+    - name: output
+      shorthand: o
+      usage: 'Output ZIP file path (default: <name>.zip)'
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+see_also:
+    - sbx kit - Manage kit artifacts

data/sbx_cli/sbx_kit_pull.yaml

@@ -0,0 +1,25 @@
+name: sbx kit pull
+synopsis: Pull a kit artifact from an OCI registry
+description: |-
+    Pull a kit artifact from an OCI registry and save it as a ZIP file.
+
+    The reference should be in the format "registry/repo:tag" or
+    "registry/repo@sha256:digest" (e.g., "ghcr.io/myorg/my-plugin:1.0").
+
+    Authentication uses your Docker credential store.
+usage: sbx kit pull REFERENCE [flags]
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for pull
+    - name: output
+      shorthand: o
+      usage: 'Output ZIP file path (default: derived from reference)'
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+see_also:
+    - sbx kit - Manage kit artifacts

data/sbx_cli/sbx_kit_push.yaml

@@ -0,0 +1,22 @@
+name: sbx kit push
+synopsis: Push a kit artifact to an OCI registry
+description: |-
+    Package and push a kit artifact directory to an OCI registry.
+
+    The directory must contain a valid spec.yaml. The reference should be
+    in the format "registry/repo:tag" (e.g., "ghcr.io/myorg/my-plugin:1.0").
+
+    Authentication uses your Docker credential store.
+usage: sbx kit push DIRECTORY REFERENCE [flags]
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for push
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+see_also:
+    - sbx kit - Manage kit artifacts

data/sbx_cli/sbx_kit_validate.yaml

@@ -0,0 +1,19 @@
+name: sbx kit validate
+synopsis: Validate a kit artifact
+description: |-
+    Validate that a directory or ZIP file is a valid kit artifact.
+
+    The reference can be a local directory, ZIP file path, or git repository.
+usage: sbx kit validate REFERENCE [flags]
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for validate
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+see_also:
+    - sbx kit - Manage kit artifacts

data/sbx_cli/sbx_login.yaml

@@ -6,6 +6,11 @@ options:
       shorthand: h
       default_value: "false"
       usage: help for login
+    - name: password-stdin
+      default_value: "false"
+      usage: Read password or access token from stdin
+    - name: username
+      usage: Docker username for non-interactive login
 inherited_options:
     - name: debug
       shorthand: D

data/sbx_cli/sbx_policy.yaml

@@ -3,9 +3,9 @@ synopsis: Manage sandbox policies
 description: |-
     Manage persistent access policies for sandboxes.
 
-    Policies are rules stored locally that control what sandboxes can access.
-    They apply globally across all sandboxes and persist across restarts.
-    Use subcommands to allow, deny, list, or remove policies.
+    Policies contain rules that control what sandboxes can access. Local rules
+    can apply globally across all sandboxes or be scoped to one sandbox. Use
+    subcommands to allow, deny, list, or remove rules.
 usage: sbx policy COMMAND
 options:
     - name: help
@@ -19,10 +19,10 @@ inherited_options:
       usage: Enable debug logging
 see_also:
     - sbx - Manage AI coding agent sandboxes.
-    - sbx policy allow - Add an allow policy for sandboxes
-    - sbx policy deny - Add a deny policy for sandboxes
+    - sbx policy allow - Add an allow rule for sandboxes
+    - sbx policy deny - Add a deny rule for sandboxes
     - sbx policy log - Show sandbox policy logs
-    - sbx policy ls - List sandbox policies
+    - sbx policy ls - List sandbox policy rules
     - sbx policy reset - Reset policies to defaults
-    - sbx policy rm - Remove a policy
+    - sbx policy rm - Remove a policy rule
     - sbx policy set-default - Set the default network policy

data/sbx_cli/sbx_policy_allow.yaml

@@ -1,10 +1,11 @@
 name: sbx policy allow
-synopsis: Add an allow policy for sandboxes
+synopsis: Add an allow rule for sandboxes
 description: |-
-    Add a policy that permits sandboxes to access specified resources.
+    Add a rule that permits sandboxes to access specified resources.
 
-    Allowed resources are accessible to all sandboxes. If a resource matches both
-    an allow and a deny rule, the deny rule takes precedence.
+    Allowed resources are accessible within the selected policy scope. If a
+    resource matches both an allow and a deny rule, the deny rule takes
+    precedence.
 usage: sbx policy allow COMMAND
 options:
     - name: help

data/sbx_cli/sbx_policy_allow_network.yaml

@@ -8,7 +8,8 @@ description: |-
     and optional port suffixes (example.com:443). Use "**" to allow all hosts.
 
     Use -g/--global to apply the rule globally to all sandboxes, or provide
-    SANDBOX before RESOURCES to scope the rule to a specific sandbox.
+    SANDBOX before RESOURCES to add the rule to policy "local" scoped to that
+    sandbox.
 usage: sbx policy allow network [-g | SANDBOX] RESOURCES [flags]
 options:
     - name: global
@@ -40,4 +41,4 @@ example: |4-
       # Allow all outbound traffic globally
       sbx policy allow network -g "**"
 see_also:
-    - sbx policy allow - Add an allow policy for sandboxes
+    - sbx policy allow - Add an allow rule for sandboxes

data/sbx_cli/sbx_policy_deny.yaml

@@ -1,7 +1,7 @@
 name: sbx policy deny
-synopsis: Add a deny policy for sandboxes
+synopsis: Add a deny rule for sandboxes
 description: |-
-    Add a policy that blocks sandboxes from accessing specified resources.
+    Add a rule that blocks sandboxes from accessing specified resources.
 
     Deny rules always take precedence over allow rules. If a resource matches
     both an allow and a deny rule, the request is blocked.

data/sbx_cli/sbx_policy_deny_network.yaml

@@ -7,7 +7,8 @@ description: |-
     Deny rules always take precedence over allow rules.
 
     Use -g/--global to apply the rule globally to all sandboxes, or provide
-    SANDBOX before RESOURCES to scope the rule to a specific sandbox.
+    SANDBOX before RESOURCES to add the rule to policy "local" scoped to that
+    sandbox.
 usage: sbx policy deny network [-g | SANDBOX] RESOURCES [flags]
 options:
     - name: global
@@ -33,4 +34,4 @@ example: |4-
       # Block all outbound traffic globally
       sbx policy deny network -g "**"
 see_also:
-    - sbx policy deny - Add a deny policy for sandboxes
+    - sbx policy deny - Add a deny rule for sandboxes

data/sbx_cli/sbx_policy_ls.yaml

@@ -1,10 +1,10 @@
 name: sbx policy ls
-synopsis: List sandbox policies
+synopsis: List sandbox policy rules
 description: |-
-    List all active policies.
+    List all active policy rules.
 
-    Displays the policy name (or ID if no name is set), type, decision
-    (allow/deny), and the associated resources for each rule.
+    Displays the provenance, scope, rule name (or ID if no name is set), type,
+    decision (allow/deny), and the associated resources for each rule.
 
     When SANDBOX is specified, only policies that apply to that sandbox are shown
     (global rules plus rules scoped to that sandbox).

data/sbx_cli/sbx_policy_rm.yaml

@@ -1,6 +1,6 @@
 name: sbx policy rm
-synopsis: Remove a policy
-description: Remove a previously added allow or deny policy.
+synopsis: Remove a policy rule
+description: Remove a previously added allow or deny rule.
 usage: sbx policy rm COMMAND
 options:
     - name: help
@@ -14,4 +14,4 @@ inherited_options:
       usage: Enable debug logging
 see_also:
     - sbx policy - Manage sandbox policies
-    - sbx policy rm network - Remove a network policy
+    - sbx policy rm network - Remove a network rule

data/sbx_cli/sbx_policy_rm_network.yaml

@@ -1,10 +1,10 @@
 name: sbx policy rm network
-synopsis: Remove a network policy
+synopsis: Remove a network rule
 description: |-
-    Remove a network policy by rule ID, resource, or both.
+    Remove a network rule by rule ID, resource, or both.
 
     Use -g/--global to remove from the global policy, or provide SANDBOX to
-    remove from a sandbox-scoped policy.
+    remove from policy "local" scoped to that sandbox.
 
     Use "sbx policy ls" to see active policies and their IDs/resources.
 usage: sbx policy rm network [-g | SANDBOX] [flags]
@@ -39,4 +39,4 @@ example: |4-
       # Remove a sandbox-scoped rule by resource
       sbx policy rm network my-sandbox --resource api.example.com
 see_also:
-    - sbx policy rm - Remove a policy
+    - sbx policy rm - Remove a policy rule

data/sbx_cli/sbx_policy_set-default.yaml

@@ -8,7 +8,7 @@ description: |-
 
     Available policies:
       allow-all   All outbound network traffic is allowed
-      balanced    Common dev traffic allowed (AI services, package registries, etc.)
+      balanced    Typical development traffic is allowed (AI services, package registries, etc.)
       deny-all    All outbound network traffic is blocked
 
     After setting defaults, use "sbx policy allow/deny" to add custom rules.

data/sbx_cli/sbx_ports.yaml

@@ -8,7 +8,10 @@ description: |-
 
     Port spec format: [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
     If HOST_PORT is omitted, an ephemeral port is allocated automatically.
-    HOST_IP defaults to 127.0.0.1, PROTOCOL defaults to tcp.
+    If HOST_IP is omitted, the port is bound on loopback, expanded based on
+    PROTOCOL and the sandbox's address families: tcp/udp binds both 127.0.0.1
+    and ::1 (or only 127.0.0.1 if the sandbox is IPv4-only); tcp4/udp4 binds
+    only 127.0.0.1; tcp6/udp6 binds only ::1. PROTOCOL defaults to tcp.
     Supported protocols: tcp, tcp4, tcp6, udp, udp4, udp6.
 usage: sbx ports SANDBOX [flags]
 options:

data/sbx_cli/sbx_rm.yaml

@@ -6,8 +6,8 @@ description: |-
     Stops running sandboxes, removes their containers, cleans up any Git
     worktrees, and deletes sandbox state. This action cannot be undone.
 
-    Use --all to remove every sandbox (requires confirmation).
-    Use --force to skip confirmation prompts (for non-interactive scripts).
+    Removal requires confirmation; use --force to skip confirmation prompts
+    (for non-interactive scripts). Use --all to remove every sandbox.
 usage: sbx rm [SANDBOX...] [flags]
 options:
     - name: all

data/sbx_cli/sbx_secret_ls.yaml

@@ -1,6 +1,6 @@
 name: sbx secret ls
 synopsis: List stored secrets
-usage: sbx secret ls [sandbox] [OPTIONS] [flags]
+usage: sbx secret ls [SANDBOX] [flags]
 options:
     - name: global
       shorthand: g

data/sbx_cli/sbx_secret_rm.yaml

@@ -1,6 +1,6 @@
 name: sbx secret rm
 synopsis: Remove a secret
-usage: sbx secret rm [-g | sandbox] [service] [flags]
+usage: sbx secret rm [-g | SANDBOX] [SERVICE] [flags]
 options:
     - name: force
       shorthand: f

data/sbx_cli/sbx_secret_set.yaml

@@ -7,7 +7,7 @@ description: |-
 
     When no arguments are provided, an interactive prompt guides you through
     scope and service selection.
-usage: sbx secret set [-g | sandbox] [service] [flags]
+usage: sbx secret set [-g | SANDBOX] [SERVICE] [flags]
 options:
     - name: force
       shorthand: f