Reference

CLI reference

The complete zeishctl command tree, grouped by workflow.

On this page

Log in with OAuth

Authenticate zeishctl with browser OAuth and PKCE.

Command: zeishctl auth login

The CLI opens the authorization URL and stores the resulting tokens in its config directory with restrictive permissions.

terminal

1zeishctl auth login2zeishctl auth status

Use an API key

Authenticate the CLI with an environment variable or stored key.

Command: zeishctl auth api-key TOKEN

ZEISH_API_KEY is preferred for automation. Use --store only when the local config should retain the key. An environment key is not written to disk.

terminal

1export ZEISH_API_KEY="zeish_live_..."2zeishctl sandboxes list3zeishctl auth api-key zeish_live_... --store

Inspect or clear CLI auth

Check the active auth method or remove stored OAuth tokens.

Command: zeishctl auth status | zeishctl auth logout

status reports whether the CLI uses an API key or OAuth. logout clears stored access and refresh tokens.

terminal

1zeishctl auth status2zeishctl auth logout

List templates, volumes, networks, and organizations

Discover the resources available to the current identity.

Command: zeishctl templates | volumes | networks | orgs

These commands return the authenticated API response as formatted JSON. Volumes and networks are organization resources and require the matching permission.

terminal

1zeishctl templates2zeishctl volumes3zeishctl networks4zeishctl orgs

List or read secrets

Inspect secret metadata or read one audited value.

Command: zeishctl secrets list | get SECRET_ID

list never includes values. get returns the value and is audited. Treat the output as sensitive.

terminal

1zeishctl secrets list2zeishctl secrets get SECRET_ID

Create, update, or delete secrets

Manage Vault-backed secrets without putting material in shell history.

Command: zeishctl secrets create | update | delete

Create and update read secret material from stdin by default. Use --value-file for a file. --value-unsafe exposes the value in argv and shell history and should be avoided.

terminal

1printf '%s' "$GITHUB_TOKEN" | zeishctl secrets create github-token \2  --provider-reference secret/data/ci/github3zeishctl secrets update SECRET_ID --name github-token-v2 < token.txt4zeishctl secrets delete SECRET_ID

Manage SSH keys

Command: zeishctl ssh-keys list | add | remove

add reads ~/.ssh/id_ed25519.pub or ~/.ssh/id_rsa.pub unless --path is supplied. Only public key material is uploaded.

terminal

1zeishctl ssh-keys list2zeishctl ssh-keys add workstation --path ~/.ssh/id_ed25519.pub3zeishctl ssh-keys remove KEY_ID

List and create sandboxes

Provision a sandbox with a template and optional resource overrides.

Command: zeishctl sandboxes list | create

create requires a name and --template-id. CPU is measured in cores, memory in MB, and region defaults to bremen.

terminal

1zeishctl sandboxes list2zeishctl sandboxes create agent-run \3  --template-id TEMPLATE_ID \4  --cpu 4 \5  --memory 4096

Inspect or clone a sandbox

Fetch sandbox detail or create a branch from an existing sandbox.

Command: zeishctl sandboxes get | clone

clone accepts an optional --name and returns the new sandbox record.

terminal

1zeishctl sandboxes get SANDBOX_ID2zeishctl sandboxes clone SANDBOX_ID --name agent-branch

Control sandbox lifecycle

Start, pause, resume, stop, or delete a sandbox.

Command: zeishctl sandboxes start | pause | resume | stop | delete

Lifecycle operations are asynchronous. Poll get or events before using a runtime-dependent operation. delete is permanent.

terminal

1zeishctl sandboxes start SANDBOX_ID2zeishctl sandboxes pause SANDBOX_ID3zeishctl sandboxes resume SANDBOX_ID4zeishctl sandboxes stop SANDBOX_ID5zeishctl sandboxes delete SANDBOX_ID

Open sandbox access

Get data-plane credentials, a browser terminal, SSH access, preview codes, or tunnel access.

Command: zeishctl sandboxes exec-access | shell | ssh | preview-code | tunnel-access

exec-access prints a scoped credential. shell opens the terminal URL. ssh uses local OpenSSH. preview-code and tunnel-access accept short-lived TTL options.

terminal

1zeishctl sandboxes exec-access SANDBOX_ID2zeishctl sandboxes shell SANDBOX_ID3zeishctl sandboxes ssh SANDBOX_ID -- -L LOCAL_PORT:REMOTE_HOST:REMOTE_PORT4zeishctl sandboxes preview-code SANDBOX_ID 3000 --ttl-seconds 6005zeishctl sandboxes tunnel-access SANDBOX_ID --ttl-seconds 60

Sync sandbox SSH keys

Apply the current user SSH key set to a running sandbox.

Command: zeishctl sandboxes sync-ssh-key SANDBOX_ID

Run this after adding or removing a user key. The sandbox must have a runtime that can receive the update.

terminal

1zeishctl sandboxes sync-ssh-key SANDBOX_ID

Read sandbox logs and events

Inspect bounded workload output and lifecycle history.

Command: zeishctl sandboxes logs | events SANDBOX_ID

Logs and events are control-plane reads. Use them to diagnose provisioning and correlate state transitions with a run.

terminal

1zeishctl sandboxes logs SANDBOX_ID2zeishctl sandboxes events SANDBOX_ID

Manage snapshots

Create, list, and delete snapshots for one sandbox.

Command: zeishctl sandboxes snapshots SANDBOX_ID

A snapshot is sandbox-scoped. Create it from a live runtime, wait until ready, then use the snapshot as a repeatable checkpoint.

terminal

1zeishctl sandboxes snapshots SANDBOX_ID create before-deploy2zeishctl sandboxes snapshots SANDBOX_ID3zeishctl sandboxes snapshots SANDBOX_ID delete SNAPSHOT_ID

Run a command

Execute a command through the sandboxd gRPC data plane.

Command: zeishctl sandboxes exec SANDBOX_ID -- COMMAND

The CLI streams stdout and stderr and prints the final exit code. It obtains scoped access automatically.

terminal

1zeishctl sandboxes exec SANDBOX_ID -- python agent.py2zeishctl sandboxes exec SANDBOX_ID -- env RUN_ID=123 ./worker

Read, write, and manage files

Use sandboxd for scoped filesystem operations.

Command: zeishctl sandboxes files SANDBOX_ID read | write | ls | mkdir | rm | mv

Paths are checked inside the sandbox file root. mkdir supports --parents, rm supports --recursive, and mv supports --overwrite.

terminal

1zeishctl sandboxes files SANDBOX_ID read /workspace/output.json2zeishctl sandboxes files SANDBOX_ID write /workspace/input.txt hello3zeishctl sandboxes files SANDBOX_ID ls /workspace --recursive4zeishctl sandboxes files SANDBOX_ID mkdir /workspace/results --parents5zeishctl sandboxes files SANDBOX_ID mv /workspace/a /workspace/b --overwrite6zeishctl sandboxes files SANDBOX_ID rm /workspace/results --recursive

Upload and download files

Stream files between the local machine and a sandbox.

Command: zeishctl sandboxes files SANDBOX_ID upload | download

Transfers use the sandboxd streaming file APIs. Use an explicit local path for output and keep large artifacts on a volume or snapshot when they must persist.

terminal

1zeishctl sandboxes files SANDBOX_ID upload ./input.json /workspace/input.json2zeishctl sandboxes files SANDBOX_ID download /workspace/output.json ./output.json

Use the API escape hatch

Call any authenticated HTTP method and path supported by the server.

Command: zeishctl api METHOD PATH [--body JSON]

The path is appended to ZEISH_API_URL. Use this for a route that does not yet have a dedicated CLI command. Responses are printed as formatted JSON.

terminal

1zeishctl api GET /api/v1/public/sandboxes2zeishctl api POST /api/v1/public/sandboxes \3  --body '{"name":"agent-run","templateId":"TEMPLATE_ID"}'

Generate completions or upgrade

Integrate zeishctl into a shell and keep it current.

Command: zeishctl completion SHELL | zeishctl upgrade

completion writes a script to stdout for bash, zsh, fish, or another supported shell. upgrade installs the latest release or a requested --version.

terminal

1zeishctl completion zsh > ~/.zsh/completions/_zeishctl2zeishctl upgrade3zeishctl upgrade --version 0.1.0

Authenticate with an API key

Authenticate the CLI with an API key.

Command: zeishctl auth api-key TOKEN --store

Use ZEISH_API_KEY for automation. Add --store only when the local config should retain the key.

terminal

1zeishctl auth api-key TOKEN --store

Log out

Clear stored OAuth credentials.

Command: zeishctl auth logout

This removes the local access and refresh tokens.

terminal

1zeishctl auth logout

Check auth status

See whether the CLI uses an API key or OAuth.

Command: zeishctl auth status

The output reports the active method without printing the credential.

terminal

1zeishctl auth status

Generate shell completions

Write completion scripts for the CLI.

Command: zeishctl completion zsh

The shell is a positional argument. Redirect the script into your shell completion directory.

terminal

1zeishctl completion zsh

Upgrade zeishctl

Install the latest or a selected CLI release.

Command: zeishctl upgrade --version 0.1.0

Omit --version to use the latest published release.

terminal

1zeishctl upgrade --version 0.1.0

List organizations

List organizations visible to the authenticated identity.

Command: zeishctl orgs

The command calls the versioned organization endpoint and prints JSON.

terminal

1zeishctl orgs

List templates

List visible sandbox templates.

Command: zeishctl templates

Use a returned template ID with sandboxes create.

terminal

1zeishctl templates

List volumes

List organization volumes.

Command: zeishctl volumes

The response includes cursor pagination when more results are available.

terminal

1zeishctl volumes

List networks

List organization networks.

Command: zeishctl networks

Use a returned network ID when creating or updating a sandbox.

terminal

1zeishctl networks

List secrets

List secret metadata.

Command: zeishctl secrets list

Values are excluded from the list response.

terminal

1zeishctl secrets list

Read a secret

Read one audited secret value.

Command: zeishctl secrets get SECRET_ID

Protect the terminal output. Secret reads are audited.

terminal

1zeishctl secrets get SECRET_ID

Create a secret

Create a Vault-backed secret from stdin or a file.

Command: zeishctl secrets create NAME --provider-reference REF < value.txt

Use --value-file for a file. Avoid --value-unsafe because it exposes material in argv.

terminal

1zeishctl secrets create NAME --provider-reference REF < value.txt

Update a secret

Update secret metadata or value.

Command: zeishctl secrets update SECRET_ID --name NAME < value.txt

Only supplied fields change. Value input follows the same safe stdin and file rules as create.

terminal

1zeishctl secrets update SECRET_ID --name NAME < value.txt

Delete a secret

Delete one secret.

Command: zeishctl secrets delete SECRET_ID

Deletion is audited and removes provider material.

terminal

1zeishctl secrets delete SECRET_ID

List SSH keys

List registered public keys.

Command: zeishctl ssh-keys list

Only public key data is returned.

terminal

1zeishctl ssh-keys list

Add an SSH key

Command: zeishctl ssh-keys add NAME --path ~/.ssh/id_ed25519.pub

If --path is omitted, the CLI checks common ed25519 and RSA public key paths.

terminal

1zeishctl ssh-keys add NAME --path ~/.ssh/id_ed25519.pub

Remove an SSH key

Revoke a registered public key.

Command: zeishctl ssh-keys remove KEY_ID

Sync the new key set into an existing sandbox separately.

terminal

1zeishctl ssh-keys remove KEY_ID

List sandboxes

List compact sandboxes in the organization.

Command: zeishctl sandboxes list

Use sandboxes get for detail and runtime metadata.

terminal

1zeishctl sandboxes list

Create a sandbox

Create a MicroVM sandbox.

Command: zeishctl sandboxes create NAME --template-id TEMPLATE_ID --cpu 4 --memory 4096

CPU is cores, memory is MB, and region defaults to bremen.

terminal

1zeishctl sandboxes create NAME --template-id TEMPLATE_ID --cpu 4 --memory 4096

Get sandbox details

Read one sandbox record.

Command: zeishctl sandboxes get SANDBOX_ID

Poll this command when waiting for an asynchronous lifecycle transition.

terminal

1zeishctl sandboxes get SANDBOX_ID

Clone a sandbox

Create a branch from an existing sandbox.

Command: zeishctl sandboxes clone SANDBOX_ID --name agent-copy

The name flag is optional.

terminal

1zeishctl sandboxes clone SANDBOX_ID --name agent-copy

Start a sandbox

Request a stopped sandbox runtime.

Command: zeishctl sandboxes start SANDBOX_ID

Wait for running before using commands, files, or desktop access.

terminal

1zeishctl sandboxes start SANDBOX_ID

Pause a sandbox

Pause a runtime while retaining state.

Command: zeishctl sandboxes pause SANDBOX_ID

Resume the sandbox before requesting data-plane work.

terminal

1zeishctl sandboxes pause SANDBOX_ID

Resume a sandbox

Resume a paused runtime.

Command: zeishctl sandboxes resume SANDBOX_ID

Poll get or events until the status is running.

terminal

1zeishctl sandboxes resume SANDBOX_ID

Stop a sandbox

Stop a runtime without deleting its record.

Command: zeishctl sandboxes stop SANDBOX_ID

Stopped sandboxes retain their configuration.

terminal

1zeishctl sandboxes stop SANDBOX_ID

Delete a sandbox

Permanently delete a sandbox.

Command: zeishctl sandboxes delete SANDBOX_ID

Deletion is irreversible.

terminal

1zeishctl sandboxes delete SANDBOX_ID

Read sandbox logs

Read captured sandbox output.

Command: zeishctl sandboxes logs SANDBOX_ID

The public API returns bounded history.

terminal

1zeishctl sandboxes logs SANDBOX_ID

Read sandbox events

Read lifecycle events.

Command: zeishctl sandboxes events SANDBOX_ID

Use events to correlate asynchronous state changes.

terminal

1zeishctl sandboxes events SANDBOX_ID

Get exec access

Mint data-plane credentials.

Command: zeishctl sandboxes exec-access SANDBOX_ID

The credential is short-lived and sandbox-scoped.

terminal

1zeishctl sandboxes exec-access SANDBOX_ID

Sync sandbox SSH keys

Apply the user's current keys to a runtime.

Command: zeishctl sandboxes sync-ssh-key SANDBOX_ID

Run this after adding or removing a user SSH key.

terminal

1zeishctl sandboxes sync-ssh-key SANDBOX_ID

Create a preview code

Mint temporary HTTP access to a port.

Command: zeishctl sandboxes preview-code SANDBOX_ID 3000 --ttl-seconds 300 --path /health

The port is positional. TTL and path are optional.

terminal

1zeishctl sandboxes preview-code SANDBOX_ID 3000 --ttl-seconds 300 --path /health

Create tunnel access

Mint WebSocket access to exposed TCP ports.

Command: zeishctl sandboxes tunnel-access SANDBOX_ID --ttl-seconds 60

Use the SDK bridge or a compatible WebSocket client.

terminal

1zeishctl sandboxes tunnel-access SANDBOX_ID --ttl-seconds 60

List sandbox snapshots

List snapshots for one sandbox.

Command: zeishctl sandboxes snapshots SANDBOX_ID

Snapshot IDs are sandbox-scoped.

terminal

1zeishctl sandboxes snapshots SANDBOX_ID

Create a sandbox snapshot

Capture a runtime checkpoint.

Command: zeishctl sandboxes snapshots SANDBOX_ID create DISPLAY_NAME

Create from a live runtime and wait for readiness.

terminal

1zeishctl sandboxes snapshots SANDBOX_ID create DISPLAY_NAME

Delete a sandbox snapshot

Delete one snapshot.

Command: zeishctl sandboxes snapshots SANDBOX_ID delete SNAPSHOT_ID

Snapshot deletion is irreversible.

terminal

1zeishctl sandboxes snapshots SANDBOX_ID delete SNAPSHOT_ID

Execute a command

Stream a command through sandboxd.

Command: zeishctl sandboxes exec SANDBOX_ID -- COMMAND

Stdout and stderr are streamed and the exit code is printed.

terminal

1zeishctl sandboxes exec SANDBOX_ID -- COMMAND

Open a shell

Open the browser terminal for a sandbox.

Command: zeishctl sandboxes shell SANDBOX_ID

The CLI prints the terminal URL and opens it when a browser is available.

terminal

1zeishctl sandboxes shell SANDBOX_ID

Connect over SSH

Connect with local OpenSSH.

Command: zeishctl sandboxes ssh SANDBOX_ID

Pass additional SSH arguments after -- and use --identity-file when needed.

terminal

1zeishctl sandboxes ssh SANDBOX_ID

Read a file

Read file contents from a sandbox.

Command: zeishctl sandboxes files SANDBOX_ID read /workspace/output.json

The path is resolved below the sandbox file root.

terminal

1zeishctl sandboxes files SANDBOX_ID read /workspace/output.json

Write a file

Write text to a sandbox file.

Command: zeishctl sandboxes files SANDBOX_ID write /workspace/input.txt hello

Parent directories are created by the CLI.

terminal

1zeishctl sandboxes files SANDBOX_ID write /workspace/input.txt hello

List a directory

List directory entries.

Command: zeishctl sandboxes files SANDBOX_ID ls /workspace --recursive

Use --recursive for nested entries.

terminal

1zeishctl sandboxes files SANDBOX_ID ls /workspace --recursive

Create a directory

Create a directory in the sandbox.

Command: zeishctl sandboxes files SANDBOX_ID mkdir /workspace/results --parents

Use --parents to create missing ancestors.

terminal

1zeishctl sandboxes files SANDBOX_ID mkdir /workspace/results --parents

Remove a path

Remove a file or directory.

Command: zeishctl sandboxes files SANDBOX_ID rm /workspace/results --recursive

Use --recursive for directories. Removing the file root is rejected.

terminal

1zeishctl sandboxes files SANDBOX_ID rm /workspace/results --recursive

Rename a path

Rename or move a path.

Command: zeishctl sandboxes files SANDBOX_ID mv /workspace/a /workspace/b --overwrite

Use --overwrite to replace an existing destination.

terminal

1zeishctl sandboxes files SANDBOX_ID mv /workspace/a /workspace/b --overwrite

Download a file

Stream a sandbox file to local storage.

Command: zeishctl sandboxes files SANDBOX_ID download /workspace/output.json ./output.json

The destination is a local path.

terminal

1zeishctl sandboxes files SANDBOX_ID download /workspace/output.json ./output.json

Upload a file

Stream a local file into the sandbox.

Command: zeishctl sandboxes files SANDBOX_ID upload ./input.json /workspace/input.json

Parent directories are created for the first upload chunk.

terminal

1zeishctl sandboxes files SANDBOX_ID upload ./input.json /workspace/input.json

Call an arbitrary API route

Use the CLI escape hatch for an HTTP operation without a named command.

Command: zeishctl api GET /api/v1/public/sandboxes

Pass JSON with --body. The request uses the configured API key or OAuth session.

terminal

1zeishctl api GET /api/v1/public/sandboxes