OpenShell/pr-preview/pr-270/reference/cli-generated.json

{"id":"reference/cli-generated","title":"OpenShell CLI Reference","url":"reference/cli-generated.html","last_modified":"2026-03-13T02:30:39.468014+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"content":"OpenShell CLI Reference\nEnvironment Variables Variable Description OPENSHELL_GATEWAY Gateway name to operate on (resolved from stored metadata). OPENSHELL_GATEWAY_ENDPOINT Gateway endpoint URL (e.g. https://gateway.example.com ). Connects directly without looking up gateway metadata. Command Tree openshell\nsandbox\n├── create [COMMAND\n├── get [NAME\n├── list\n├── delete [NAME\n├── connect [NAME\n├── upload <NAME> <LOCAL_PATH> [DEST\n├── download <NAME> <SANDBOX_PATH> [DEST\n└── ssh-config [NAME\nforward\n├── start <PORT> [NAME\n├── stop <PORT> [NAME\n└── list\nlogs [NAME\npolicy\n├── set [NAME\n├── get [NAME\n└── list [NAME\nprovider\n├── create\n├── get <NAME\n├── list\n├── update <NAME\n└── delete <NAME\ngateway\n├── start\n├── stop\n├── destroy\n├── add <ENDPOINT\n├── login [NAME\n├── select [NAME\n└── info\nstatus\ninference\n├── set\n├── update\n└── get\nterm\ncompletions <SHELL\nSandbox Commands Manage sandboxes. openshell sandbox create [COMMAND] Create a sandbox. Flag Description --name <NAME> Optional sandbox name (auto-generated when omitted). --from <FROM> Sandbox source: a community sandbox name (e.g., openclaw ), a path to a Dockerfile or directory containing one, or a full container image reference (e.g., myregistry.com/img:tag ). --upload <UPLOAD> Upload local files into the sandbox before running. --no-git-ignore Disable .gitignore filtering for --upload . --no-keep Delete the sandbox after the initial command or shell exits. --editor <EDITOR> Launch a remote editor after the sandbox is ready. Keeps the sandbox alive and installs OpenShell-managed SSH config. --remote <REMOTE> SSH destination for remote bootstrap (e.g., user@hostname). Only used when no cluster exists yet; ignored if a cluster is already active. --ssh-key <SSH_KEY> Path to SSH private key for remote bootstrap. --provider <PROVIDERS> Provider names to attach to this sandbox. --policy <POLICY> Path to a custom sandbox policy YAML file. Overrides the built-in default and the OPENSHELL_SANDBOX_POLICY env var. --forward <FORWARD> Forward a local port to the sandbox before the initial command or shell starts. Keeps the sandbox alive. --tty Allocate a pseudo-terminal for the remote command. Defaults to auto-detection (on when stdin and stdout are terminals). Use –tty to force a PTY even when auto-detection fails, or –no-tty to disable. --no-tty Disable pseudo-terminal allocation. --no-bootstrap Never bootstrap a gateway automatically; error if none is available. --auto-providers Auto-create missing providers from local credentials. --no-auto-providers Never auto-create providers; error if required providers are missing. [COMMAND] Command to run after “–” (defaults to an interactive shell). openshell sandbox get [NAME] Fetch a sandbox by name. Flag Description [NAME] Sandbox name (defaults to last-used sandbox). openshell sandbox list List sandboxes. Flag Default Description --limit <LIMIT> 100 Maximum number of sandboxes to return. --offset <OFFSET> 0 Offset into the sandbox list. --ids Print only sandbox ids (one per line). --names Print only sandbox names (one per line). openshell sandbox delete [NAME] Delete a sandbox by name. Flag Description [NAME] Sandbox names. --all Delete all sandboxes. openshell sandbox connect [NAME] Connect to a sandbox. When no name is given, reconnects to the last-used sandbox. Flag Description [NAME] Sandbox name (defaults to last-used sandbox). --editor <EDITOR> Launch a remote editor instead of an interactive shell. Installs OpenShell-managed SSH config if needed. openshell sandbox upload <NAME> <LOCAL_PATH> [DEST] Upload local files to a sandbox. Flag Description <NAME> Sandbox name. <LOCAL_PATH> Local path to upload. [DEST] Destination path in the sandbox (defaults to /sandbox ). --no-git-ignore Disable .gitignore filtering (uploads everything). openshell sandbox download <NAME> <SANDBOX_PATH> [DEST] Download files from a sandbox. Flag Description <NAME> Sandbox name. <SANDBOX_PATH> Sandbox path to download. [DEST] Local destination (defaults to . ). openshell sandbox ssh-config [NAME] Print an SSH config entry for a sandbox. Outputs a Host block suitable for appending to ~/.ssh/config, enabling tools like VSCode Remote-SSH to connect to the sandbox. Flag Description [NAME] Sandbox name (defaults to last-used sandbox). Forward Commands Manage port forwarding to a sandbox. openshell forward start <PORT> [NAME] Start forwarding a local port to a sandbox. Flag Description <PORT> Port to forward (used as both local and remote port). [NAME] Sandbox name (defaults to last-used sandbox). -d , --background Run the forward in the background and exit immediately. openshell forward stop <PORT> [NAME] Stop a background port forward. Flag Description <PORT> Port that was forwarded. [NAME] Sandbox name (defaults to last-used sandbox). openshell forward list List active port forwards. Policy Commands Manage sandbox policy. openshell policy set [NAME] Update policy on a live sandbox. Flag Default Description [NAME] Sandbox name (defaults to last-used sandbox). --policy <POLICY> Path to the policy YAML file. --wait Wait for the sandbox to load the policy. --timeout <TIMEOUT> 60 Timeout for –wait in seconds. openshell policy get [NAME] Show current active policy for a sandbox. Flag Default Description [NAME] Sandbox name (defaults to last-used sandbox). --rev <REV> 0 Show a specific policy revision (default: latest). --full Print the full policy as YAML. openshell policy list [NAME] List policy history for a sandbox. Flag Default Description [NAME] Sandbox name (defaults to last-used sandbox). --limit <LIMIT> 20 Maximum number of revisions to return. Provider Commands Manage provider configuration. openshell provider create Create a provider config. Flag Description --name <NAME> Provider name. --type <PROVIDER_TYPE> Provider type. --from-existing Load provider credentials/config from existing local state. --credential <KEY[=VALUE]> Provider credential pair ( KEY=VALUE ) or env lookup key ( KEY ). --config <KEY=VALUE> Provider config key/value pair. openshell provider get <NAME> Fetch a provider by name. Flag Description <NAME> Provider name. openshell provider list List providers. Flag Default Description --limit <LIMIT> 100 Maximum number of providers to return. --offset <OFFSET> 0 Offset into the provider list. --names Print only provider names, one per line. openshell provider update <NAME> Update an existing provider’s credentials or config. Flag Description <NAME> Provider name. --from-existing Re-discover credentials from existing local state (e.g. env vars, config files). --credential <KEY[=VALUE]> Provider credential pair ( KEY=VALUE ) or env lookup key ( KEY ). --config <KEY=VALUE> Provider config key/value pair. openshell provider delete <NAME> Delete providers by name. Flag Description <NAME> Provider names. Gateway Commands Manage the gateway lifecycle. openshell gateway start Deploy/start the gateway. Flag Default Description --name <NAME> openshell Gateway name. Env: OPENSHELL_GATEWAY . --remote <REMOTE> SSH destination for remote deployment (e.g., user@hostname). --ssh-key <SSH_KEY> Path to SSH private key for remote deployment. --port <PORT> 8080 Host port to map to the gateway (default: 8080). --gateway-host <GATEWAY_HOST> Override the gateway host written into cluster metadata. --recreate Destroy and recreate the gateway from scratch if one already exists. --plaintext Listen on plaintext HTTP instead of mTLS. --disable-gateway-auth Disable gateway authentication (mTLS client certificate requirement). --registry-token <REGISTRY_TOKEN> Authentication token for pulling container images from ghcr.io. Env: OPENSHELL_REGISTRY_TOKEN . --gpu Enable NVIDIA GPU passthrough. openshell gateway stop Stop the gateway (preserves state). Flag Description --name <NAME> Gateway name (defaults to active gateway). Env: OPENSHELL_GATEWAY . --remote <REMOTE> Override SSH destination (auto-resolved from gateway metadata). --ssh-key <SSH_KEY> Path to SSH private key for remote gateway. openshell gateway destroy Destroy the gateway and its state. Flag Description --name <NAME> Gateway name (defaults to active gateway). Env: OPENSHELL_GATEWAY . --remote <REMOTE> Override SSH destination (auto-resolved from gateway metadata). --ssh-key <SSH_KEY> Path to SSH private key for remote gateway. openshell gateway add <ENDPOINT> Add an existing gateway. Registers a gateway endpoint so it appears in openshell gateway select . Without extra flags the gateway is treated as an edge-authenticated (cloud) gateway and a browser is opened for authentication. Pass --remote <ssh-dest> to register a remote mTLS gateway whose Docker daemon is reachable over SSH. Pass --local to register a local mTLS gateway running in Docker on this machine. In both cases the CLI extracts mTLS certificates from the running container automatically. An ssh:// endpoint (e.g., ssh://user@host:8080 ) is shorthand for --remote user@host with the endpoint derived from the URL. Flag Description <ENDPOINT> Gateway endpoint URL (e.g., https://10.0.0.5:8080 or ssh://user@host:8080 ). --name <NAME> Gateway name (auto-derived from the endpoint hostname when omitted). --remote <REMOTE> Register a remote mTLS gateway accessible via SSH. --ssh-key <SSH_KEY> SSH private key for the remote host (used with --remote or ssh:// ). --local Register a local mTLS gateway running in Docker on this machine. openshell gateway login [NAME] Authenticate with an edge-authenticated gateway. Opens a browser for the edge proxy’s login flow and stores the token locally. Use this to re-authenticate when a token expires. Flag Description [NAME] Gateway name (defaults to the active gateway). openshell gateway select [NAME] Select the active gateway. When called without a name, opens an interactive chooser on a TTY and lists available gateways in non-interactive mode. Flag Description [NAME] Gateway name (omit to choose interactively or list in non-interactive mode). openshell gateway info Show gateway deployment details. Flag Description --name <NAME> Gateway name (defaults to active gateway). Env: OPENSHELL_GATEWAY . Inference Commands Manage inference configuration. openshell inference set Set gateway-level inference provider and model. Flag Description --provider <PROVIDER> Provider name. --model <MODEL> Model identifier to force for generation calls. --system Configure the system inference route instead of the user-facing route. System inference is used by platform functions (e.g. the agent harness) and is not accessible to user code. openshell inference update Update gateway-level inference configuration (partial update). Flag Description --provider <PROVIDER> Provider name (unchanged if omitted). --model <MODEL> Model identifier (unchanged if omitted). --system Target the system inference route. openshell inference get Get gateway-level inference provider and model. Flag Description --system Show the system inference route instead of the user-facing route. When omitted, both routes are displayed. Additional Commands openshell logs [NAME] View sandbox logs. Flag Default Description [NAME] Sandbox name (defaults to last-used sandbox). -n <N> 200 Number of log lines to return. --tail Stream live logs. --since <SINCE> Only show logs from this duration ago (e.g. 5m, 1h, 30s). --source <SOURCE> all Filter by log source: “gateway”, “sandbox”, or “all” (default). Can be specified multiple times: –source gateway –source sandbox. --level <LEVEL> Minimum log level to display: error, warn, info (default), debug, trace. openshell status Show gateway status and information. openshell term Launch the OpenShell interactive TUI. Flag Default Description --theme <THEME> auto Color theme for the TUI: auto, dark, or light. Env: OPENSHELL_THEME . openshell completions <SHELL> Generate shell completions. Flag Description <SHELL> Shell to generate completions for","format":"text","summary":"Gateway name to operate on (resolved from stored metadata).","headings":[{"text":"OpenShell CLI Reference","level":1},{"text":"Environment Variables","level":2},{"text":"Command Tree","level":2},{"text":"Sandbox Commands","level":2},{"text":"openshell sandbox create [COMMAND]","level":3},{"text":"openshell sandbox get [NAME]","level":3},{"text":"openshell sandbox list","level":3},{"text":"openshell sandbox delete [NAME]","level":3},{"text":"openshell sandbox connect [NAME]","level":3},{"text":"openshell sandbox upload <NAME> <LOCAL_PATH> [DEST]","level":3},{"text":"openshell sandbox download <NAME> <SANDBOX_PATH> [DEST]","level":3},{"text":"openshell sandbox ssh-config [NAME]","level":3},{"text":"Forward Commands","level":2},{"text":"openshell forward start <PORT> [NAME]","level":3},{"text":"openshell forward stop <PORT> [NAME]","level":3},{"text":"openshell forward list","level":3},{"text":"Policy Commands","level":2},{"text":"openshell policy set [NAME]","level":3},{"text":"openshell policy get [NAME]","level":3},{"text":"openshell policy list [NAME]","level":3},{"text":"Provider Commands","level":2},{"text":"openshell provider create","level":3},{"text":"openshell provider get <NAME>","level":3},{"text":"openshell provider list","level":3},{"text":"openshell provider update <NAME>","level":3},{"text":"openshell provider delete <NAME>","level":3},{"text":"Gateway Commands","level":2},{"text":"openshell gateway start","level":3},{"text":"openshell gateway stop","level":3},{"text":"openshell gateway destroy","level":3},{"text":"openshell gateway add <ENDPOINT>","level":3},{"text":"openshell gateway login [NAME]","level":3},{"text":"openshell gateway select [NAME]","level":3},{"text":"openshell gateway info","level":3},{"text":"Inference Commands","level":2},{"text":"openshell inference set","level":3},{"text":"openshell inference update","level":3},{"text":"openshell inference get","level":3},{"text":"Additional Commands","level":2},{"text":"openshell logs [NAME]","level":3},{"text":"openshell status","level":3},{"text":"openshell term","level":3},{"text":"openshell completions <SHELL>","level":3}]}