Interfaces

Command-line interfaces

Use the separate management, runtime, and observability command-line clients.

On this page+

Choose a client
First commands
Global options
Authentication and connection
Arguments and shell quoting
Output and exit status
Generated help

Choose a client

Ephemeral Sandbox intentionally has no combined CLI. Each executable exposes one fixed authority and sends semantic requests through the authenticated gateway.

Management CLI

sandbox-manager-cli

Eight operations for host discovery, lifecycle, compaction, and export.

Open the reference

Runtime CLI

sandbox-runtime-cli --sandbox-id ID

Seven operations for command sessions, files, and attribution.

Open the reference

Observability CLI

sandbox-observability-cli

Five read-only operations for health, telemetry, resources, and layers.

Open the reference

First commands

List manager-known sandboxes, run a command in one, then inspect its live state.

Shell

sandbox-manager-cli list_sandboxes
sandbox-runtime-cli --sandbox-id ID exec_command pwd
sandbox-observability-cli snapshot --sandbox-id ID

Global options

Option	Clients	Purpose
`--gateway-socket HOST:PORT`	All	Override gateway discovery.
`--gateway-auth-token TOKEN`	All	Override token discovery.
`--progress`	Management	Stream gateway log lines to stderr, especially during creation.
`--sandbox-id ID`	Runtime	Select required sandbox gateway scope.
`--request-id VALUE`	Runtime	Supply a stable request identity for correlation and attribution.

Authentication and connection

Repository launchers in bin/ load SANDBOX_GATEWAY_AUTH_TOKEN from ~/.ephemeral-sandbox/gateway.token by default. SANDBOX_GATEWAY_TOKEN_FILE can select a service-managed path. The token file must not be group- or world-accessible.

Shell

bin/sandbox-gateway-token ensure
bin/sandbox-manager-cli list_sandboxes

Direct binaries discover the same connection from flags or environment. Use explicit token flags only in controlled automation because command arguments may be visible to other processes or retained in shell history.

Arguments and shell quoting

Global options may appear around the operation, while operation arguments follow the operation’s generated usage. Quote command text, file content, and edit JSON so the local shell passes one value unchanged.

Shell

sandbox-runtime-cli --sandbox-id ID exec_command 'printf "%s\n" ready'
sandbox-runtime-cli --sandbox-id ID file_edit --path notes.txt \
  --edits '[{"old_string":"draft","new_string":"ready"}]'

Output and exit status

Success writes one JSON response to stdout. Remote and transport errors write a JSON envelope to stderr. Local syntax, argument validation, and configuration errors also use stderr.

Exit	Meaning
`0`	Help or operation succeeded.
`1`	Transport or remote operation failed.
`2`	Local syntax, validation, or configuration failed.

Generated help

Each binary’s catalog-derived help is the final authority for installed syntax. Catalog help lists operations; operation help includes the description, usage, argument types, defaults, examples, and related operations.

Shell

sandbox-manager-cli help create_sandbox
sandbox-runtime-cli --sandbox-id ID help exec_command
sandbox-observability-cli help layerstack