OpenShell/.agents/skills/openshell-cli/cli-reference.md

OpenShell CLI Reference

Quick-reference for the openshell command-line interface. For workflow guidance, see SKILL.md.

Self-teaching: If a command or flag is not listed here, use openshell <command> --help to discover it. The CLI has comprehensive built-in help at every level.

Global Options

Flag	Description
-v, --verbose	Increase verbosity (-v = info, -vv = debug, -vvv = trace)
-g, --gateway <NAME>	Gateway to operate on. Also settable via OPENSHELL_GATEWAY env var. Falls back to active gateway in ~/.config/openshell/active_gateway.

Environment Variables

Variable	Description
OPENSHELL_GATEWAY	Override active gateway name (same as --gateway)
OPENSHELL_SANDBOX_POLICY	Path to default sandbox policy YAML (fallback when --policy is not provided)

---

Complete Command Tree

openshell
├── gateway
│   ├── start [opts]
│   ├── stop [opts]
│   ├── destroy [opts]
│   ├── info [--name]
│   └── select [name]
├── status
├── inference
│   ├── set --provider --model
│   ├── update [--provider] [--model]
│   └── get
├── sandbox
│   ├── create [opts] [-- CMD...]
│   ├── get <name>
│   ├── list [opts]
│   ├── delete <name>...
│   ├── connect <name>
│   ├── upload <name> <path> [dest]
│   ├── download <name> <path> [dest]
│   ├── ssh-config <name>
│   └── image
│       └── push [opts]
├── forward
│   ├── start <port> <name> [-d]
│   ├── stop <port> <name>
│   └── list
├── logs <name> [opts]
├── policy
│   ├── set <name> --policy <path> [--wait]
│   ├── get <name> [--full]
│   └── list <name>
├── provider
│   ├── create --name --type [opts]
│   ├── get <name>
│   ├── list [opts]
│   ├── update <name> --type [opts]
│   └── delete <name>...
├── doctor
│   ├── logs [--name] [-n] [--tail] [--remote] [--ssh-key]
│   └── exec [--name] [--remote] [--ssh-key] -- <command...>
├── term
├── completions <shell>
└── ssh-proxy [opts]

---

Gateway Commands

openshell gateway start

Provision or start a cluster (local or remote).

Flag	Default	Description
--name <NAME>	openshell	Cluster name
--remote <USER@HOST>	none	SSH destination for remote deployment
--ssh-key <PATH>	none	SSH private key for remote deployment
--port <PORT>	8080	Host port mapped to gateway
--gateway-host <HOST>	none	Override gateway host in metadata
--recreate	false	Destroy and recreate from scratch if a gateway already exists (skips interactive prompt)

openshell gateway stop

Stop a cluster (preserves state for later restart).

Flag	Description
--name <NAME>	Cluster name (defaults to active)
--remote <USER@HOST>	SSH destination
--ssh-key <PATH>	SSH private key

openshell gateway destroy

Destroy a cluster and all its state. Same flags as stop.

openshell gateway info

Show deployment details: endpoint and remote host.

Flag	Description
--name <NAME>	Cluster name (defaults to active)

openshell gateway select [name]

Set the active gateway. Writes to ~/.config/openshell/active_gateway. When called without arguments, lists all provisioned gateways with the active one marked with *.

---

Doctor Commands

openshell doctor logs

Fetch logs from the gateway Docker container.

Flag	Default	Description
--name <NAME>	active gateway	Gateway name
-n, --lines <N>	all	Number of log lines to return
--tail	false	Stream live logs (follow mode)
--remote <USER@HOST>	auto-resolved	SSH destination for remote gateways
--ssh-key <PATH>	none	SSH private key for remote gateways

openshell doctor exec -- <COMMAND...>

Run a command inside the gateway container with KUBECONFIG pre-configured. Launches an interactive docker exec session (tunnelled over SSH for remote gateways).

Flag	Default	Description
--name <NAME>	active gateway	Gateway name
--remote <USER@HOST>	auto-resolved	SSH destination for remote gateways
--ssh-key <PATH>	none	SSH private key for remote gateways

Examples:

• openshell doctor exec -- kubectl get pods -A
• openshell doctor exec -- k9s
• openshell doctor exec -- sh (interactive shell)

---

Status Command

openshell status

Show server connectivity and version for the active gateway.

---

Sandbox Commands

openshell sandbox create [OPTIONS] [-- COMMAND...]

Create a sandbox, wait for readiness, then connect or execute the trailing command. Auto-bootstraps a cluster if none exists.

Flag	Description
--name <NAME>	Sandbox name (auto-generated if omitted)
--from <SOURCE>	Sandbox source: community name, Dockerfile path, directory, or image reference (BYOC)
--upload <PATH>[:<DEST>]	Upload local files into sandbox (default dest: /sandbox)
--no-keep	Delete sandbox after the initial command or shell exits
--provider <NAME>	Provider to attach (repeatable)
--policy <PATH>	Path to custom policy YAML
--forward <PORT>	Forward local port to sandbox (keeps the sandbox alive)
--remote <USER@HOST>	SSH destination for auto-bootstrap
--ssh-key <PATH>	SSH private key for auto-bootstrap
--tty	Force pseudo-terminal allocation
--no-tty	Disable pseudo-terminal allocation
--bootstrap	Auto-bootstrap a gateway if none is available (skips interactive prompt)
--no-bootstrap	Never auto-bootstrap; error immediately if no gateway is available
--auto-providers	Auto-create missing providers from local credentials (skips interactive prompt)
--no-auto-providers	Never auto-create providers; skip missing providers silently
[-- COMMAND...]	Command to execute (defaults to interactive shell)

openshell sandbox get <name>

Show sandbox details (id, name, namespace, phase, policy).

openshell sandbox list

List sandboxes in a table.

Flag	Default	Description
--limit <N>	100	Max sandboxes to return
--offset <N>	0	Pagination offset
--ids	false	Print only sandbox IDs
--names	false	Print only sandbox names

openshell sandbox delete <NAME>...

Delete one or more sandboxes by name. Stops any background port forwards.

openshell sandbox connect <name>

Open an interactive SSH shell to a sandbox.

openshell sandbox upload <name> <path> [dest]

Upload local files to a sandbox using tar-over-SSH.

Argument	Default	Description
<name>	--	Sandbox name (required)
<path>	--	Local path to upload (required)
[dest]	/sandbox	Destination path in sandbox

openshell sandbox download <name> <path> [dest]

Download files from a sandbox using tar-over-SSH.

Argument	Default	Description
<name>	--	Sandbox name (required)
<path>	--	Sandbox path to download (required)
[dest]	.	Local destination path

openshell sandbox ssh-config <name>

Print an SSH config Host block for a sandbox. Useful for VS Code Remote-SSH.

---

Port Forwarding Commands

openshell forward start <port> <name>

Start forwarding a local port to a sandbox.

Flag	Description
<port>	Port number (used as both local and remote)
<name>	Sandbox name
-d, --background	Run in background

openshell forward stop <port> <name>

Stop a background port forward.

openshell forward list

List all active port forwards (sandbox, port, PID, status).

---

Logs Command

openshell logs <name>

View sandbox logs. Supports one-shot and streaming.

Flag	Default	Description
-n <N>	200	Number of log lines
--tail	false	Stream live logs
--since <DURATION>	none	Only show logs from this duration ago (e.g., 5m, 1h)
--source <SOURCE>	all	Filter: gateway, sandbox, or all (repeatable)
--level <LEVEL>	none	Minimum level: error, warn, info, debug, trace

---

Policy Commands

openshell policy set <name> --policy <PATH>

Update the policy on a live sandbox. Only dynamic fields (network_policies, inference) can be changed at runtime.

Flag	Default	Description
--policy <PATH>	--	Path to policy YAML (required)
--wait	false	Wait for sandbox to confirm policy is loaded
--timeout <SECS>	60	Timeout for --wait

Exit codes with --wait: 0 = loaded, 1 = failed, 124 = timeout.

openshell policy get <name>

Show current active policy for a sandbox.

Flag	Default	Description
--rev <VERSION>	0 (latest)	Show a specific revision
--full	false	Print the full policy as YAML (round-trips with --policy input)

openshell policy list <name>

List policy revision history (version, hash, status, created, error).

Flag	Default	Description
--limit <N>	20	Max revisions to return

---

Provider Commands

Supported provider types: claude, opencode, codex, generic, nvidia, gitlab, github, outlook.

openshell provider create --name <NAME> --type <TYPE>

Create a provider configuration.

Flag	Description
--name <NAME>	Provider name (required)
--type <TYPE>	Provider type (required)
--from-existing	Load credentials from local state (mutually exclusive with --credential)
--credential KEY[=VALUE]	Credential pair. Bare KEY reads from env var. Repeatable.
--config KEY=VALUE	Config key/value pair. Repeatable.

openshell provider get <name>

Show provider details (id, name, type, credential keys, config keys).

openshell provider list

List providers in a table.

Flag	Default	Description
--limit <N>	100	Max providers
--offset <N>	0	Pagination offset
--names	false	Print only names

openshell provider update <name> --type <TYPE>

Update an existing provider. Same flags as create.

openshell provider delete <NAME>...

Delete one or more providers by name.

---

Inference Commands

openshell inference set

Configure the managed gateway inference route used by inference.local. Both flags are required.

Flag	Default	Description
--provider <NAME>	--	Provider record name (required)
--model <ID>	--	Model identifier to use for generation requests (required)

openshell inference update

Partially update the gateway inference configuration. Fetches the current config and applies only the provided overrides. At least one flag is required.

Flag	Default	Description
--provider <NAME>	unchanged	Provider record name
--model <ID>	unchanged	Model identifier

openshell inference get

Show the current gateway inference configuration.

---

Other Commands

openshell term

Launch the OpenShell interactive TUI.

openshell completions <shell>

Generate shell completion scripts. Supported shells: bash, fish, zsh, powershell.

openshell ssh-proxy

SSH proxy used as a ProxyCommand. Not typically invoked directly.