CLI reference
Every command of the sandscale CLI, with its usage, options and examples. This page is generated from the CLI's own command registry, so it matches the CLI you install.
Overview
Sandscale CLI: your Sandscale cloud workspaces, sandboxes, build hosts and vault from the terminal.
Usage:
sandscale <command> [args] (sandscale help <command> for its options and examples)
Commands:
login Sign in to Sandscale (browser with PKCE; --device for a code on another device)
logout Sign out (revokes the session and deletes the local tokens)
whoami Who is signed in
workspace Cloud workspaces
sandbox Sandboxes
build Build hosts and lab hosts: pools, your leases, runs and their logs
vault Sandscale Vault: KV secrets, policies, leases, transit, mounts and audit devices
logs Logs of a workspace, a sandbox or a build host run
mcp An MCP server (stdio) with your workspaces, sandboxes and build hosts as tools
help Help for a command
version Print the version
Configuration: ~/.sandscale (SANDSCALE_CONFIG_DIR). Sign-in: auth.sandscale.dev. API: api.sandscale.dev. sandscale login
Sign in to Sandscale (browser with PKCE; --device for a code on another device)
sandscale login: Sign in to Sandscale (browser with PKCE; --device for a code on another device)
Usage:
sandscale login [--device] [--no-browser]
Your own login at auth.sandscale.dev. The tokens are kept in the OS credential store under "Sandscale CLI", never in a file, and never shared with other apps.
Examples:
sandscale login
sandscale login --device sandscale logout
Sign out (revokes the session and deletes the local tokens)
sandscale logout: Sign out (revokes the session and deletes the local tokens)
Usage:
sandscale logout
Examples:
sandscale logout sandscale whoami
Who is signed in
sandscale whoami: Who is signed in
Usage:
sandscale whoami [--json]
Examples:
sandscale whoami sandscale workspace
Cloud workspaces
Uses your own Sandscale sign-in (sandscale login). Sharing a workspace and its credentials stay in the console. Not here: config-ssh (use sandscale workspace ssh or port-forward).
| Command | What it does |
|---|---|
workspace list | Your workspaces |
workspace show | One workspace |
workspace create | Create a workspace from a template |
workspace open | Start it when stopped, wait until it runs, then ssh (or a terminal); with --ide, open it in an editor |
workspace ssh | The system ssh through Sandscale, with a short-lived certificate and a checked host key |
workspace logs | The workspace agent's or a build's logs |
workspace stop | Stop a workspace |
workspace restart | Stop it, wait until it stopped, then start it |
workspace update | Rebuild it on its template's active version |
workspace rename | Rename a workspace (your own sign-in) |
workspace delete | Delete a workspace and its disks (your own sign-in; Sandscale may ask you to confirm it is you) |
workspace port-forward | Forward local ports to a workspace's ports (until Ctrl+C) |
workspace schedule | Show or set when it starts, stops after a start, and stops when idle |
workspace templates | Templates you may create workspaces from |
workspace dotfiles | Your dotfiles repository, applied to workspaces (your own sign-in) |
workspace ping | Round trips to Sandscale and the state of the workspace agent |
workspace stat | CPU, memory and disk the workspace agent last reported |
workspace support-bundle | A JSON file for support: the workspace, its agent, builds and logs, with tokens and secrets removed |
workspace ssh-cert | Make sure the workspace key and a fresh SSH certificate are on disk |
workspace ssh-proxy | ssh's ProxyCommand: for tools that run their own ssh |
sandscale workspace list
sandscale workspace list: Your workspaces
Usage:
sandscale workspace list [--project ID] [--limit N] [--cursor C] [--json]
Examples:
sandscale workspace list
sandscale workspace list --json sandscale workspace show
sandscale workspace show: One workspace
Usage:
sandscale workspace show NAME|ID [--json]
Examples:
sandscale workspace show payments-dev sandscale workspace create
sandscale workspace create: Create a workspace from a template
Usage:
sandscale workspace create NAME --template ID [--template-version ID] [--param KEY=VALUE]... [--ttl 8h] [--json]
Examples:
sandscale workspace create payments-dev --template go-service --param region=eu1 sandscale workspace open
sandscale workspace open: Start it when stopped, wait until it runs, then ssh (or a terminal); with --ide, open it in an editor
Usage:
sandscale workspace open NAME|ID [--terminal] [--no-connect] [--json]
sandscale workspace open NAME|ID --ide browser [--start] [--json]
Start it when stopped, wait until it runs, then ssh (or a terminal). --ide browser opens it in the browser; editors that connect over SSH use sandscale workspace ssh.
Examples:
sandscale workspace open payments-dev
sandscale workspace open payments-dev --terminal
sandscale workspace open payments-dev --ide vscode --start sandscale workspace ssh
sandscale workspace ssh: The system ssh through Sandscale, with a short-lived certificate and a checked host key
Usage:
sandscale workspace ssh NAME|ID [--user USER] [--ssh-arg ARG]... [-- COMMAND [ARG...]]
ssh uses a key made once for this workspace (in ~/.sandscale/ssh/<id>/) and a certificate Sandscale signs for it, valid for 10 minutes and renewed when less than 2 minutes remain. The workspace's host key is checked against Sandscale's host CA, or the key its agent registered; host key checking is never turned off. Everything after -- is the command the workspace runs (ssh joins its words with spaces, as ssh does). Options for ssh itself go in --ssh-arg, one word each. Forwarding ports: workspace port-forward.
Examples:
sandscale workspace ssh payments-dev
sandscale workspace ssh payments-dev -- ls -la /srv
sandscale workspace ssh payments-dev --ssh-arg=-A -- git pull sandscale workspace logs
sandscale workspace logs: The workspace agent's or a build's logs
Usage:
sandscale workspace logs NAME|ID [--build ID|latest] [--follow] [--after N] [--limit N] [--json]
Examples:
sandscale workspace logs payments-dev --follow
sandscale workspace logs payments-dev --build latest sandscale workspace stop
sandscale workspace stop: Stop a workspace
Usage:
sandscale workspace stop NAME|ID [--json]
Examples:
sandscale workspace stop payments-dev sandscale workspace restart
sandscale workspace restart: Stop it, wait until it stopped, then start it
Usage:
sandscale workspace restart NAME|ID [--json]
Examples:
sandscale workspace restart payments-dev sandscale workspace update
sandscale workspace update: Rebuild it on its template's active version
Usage:
sandscale workspace update NAME|ID [--param KEY=VALUE]... [--json]
Changes nothing when it already runs the active version (unless --param is given).
Examples:
sandscale workspace update payments-dev sandscale workspace rename
sandscale workspace rename: Rename a workspace (your own sign-in)
Usage:
sandscale workspace rename NAME|ID NEW-NAME [--json]
Examples:
sandscale workspace rename payments-dev payments-old sandscale workspace delete
sandscale workspace delete: Delete a workspace and its disks (your own sign-in; Sandscale may ask you to confirm it is you)
Usage:
sandscale workspace delete NAME|ID [--yes] [--json]
You type the workspace's name to confirm, or pass --yes. When Sandscale asks you to confirm it is you, the CLI asks at this terminal (authenticator code, emailed code, or your passkey in the console); without a terminal nothing is asked, nothing is deleted, and the exit code is 4.
Examples:
sandscale workspace delete payments-old sandscale workspace port-forward
sandscale workspace port-forward: Forward local ports to a workspace's ports (until Ctrl+C)
Usage:
sandscale workspace port-forward NAME|ID LOCAL:REMOTE... [--bind ADDRESS] [--user USER]
sandscale workspace port-forward NAME|ID --tcp [127.0.0.1:]LOCAL:REMOTE... [--user USER]
Each LOCAL:REMOTE (or one port for both) listens on this computer and reaches that port on the workspace, through ssh. It listens on 127.0.0.1 only; --bind 0.0.0.0 (or another address, or *) makes it reachable from your network and prints a warning. --tcp takes a loopback address only. At most 32 forwards.
Examples:
sandscale workspace port-forward payments-dev 8080:80
sandscale workspace port-forward payments-dev 3000 5432:5432
sandscale workspace port-forward payments-dev --tcp 8080:3000 sandscale workspace schedule
sandscale workspace schedule: Show or set when it starts, stops after a start, and stops when idle
Usage:
sandscale workspace schedule show NAME|ID [--json]
sandscale workspace schedule start NAME|ID "CRON"|off [--timezone ZONE] [--json]
sandscale workspace schedule stop NAME|ID DURATION|off [--json]
sandscale workspace schedule idle NAME|ID DURATION|default [--json]
CRON has 5 fields (minute hour day month weekday); the time zone defaults to this machine's. Setting needs your own sign-in; your organization's policy can shorten what you set (show prints the effective values).
Examples:
sandscale workspace schedule show payments-dev
sandscale workspace schedule start payments-dev "30 8 * * 1-5" --timezone Europe/Berlin
sandscale workspace schedule stop payments-dev 8h sandscale workspace templates
sandscale workspace templates: Templates you may create workspaces from
Usage:
sandscale workspace templates list [--json]
sandscale workspace templates show NAME|ID [--json]
Examples:
sandscale workspace templates list
sandscale workspace templates show go-service sandscale workspace dotfiles
sandscale workspace dotfiles: Your dotfiles repository, applied to workspaces (your own sign-in)
Usage:
sandscale workspace dotfiles show [--json]
sandscale workspace dotfiles set URL [--branch B] [--install-script PATH] [--target-path PATH] [--auto-sync] [--json]
sandscale workspace dotfiles remove [--json]
sandscale workspace dotfiles sync NAME|ID [--json]
URL is https://, ssh:// or git@host:path, with no user name, password or token in it.
Examples:
sandscale workspace dotfiles set https://github.com/me/dotfiles
sandscale workspace dotfiles sync payments-dev sandscale workspace ping
sandscale workspace ping: Round trips to Sandscale and the state of the workspace agent
Usage:
sandscale workspace ping NAME|ID [--count N] [--json]
Examples:
sandscale workspace ping payments-dev --count 5 sandscale workspace stat
sandscale workspace stat: CPU, memory and disk the workspace agent last reported
Usage:
sandscale workspace stat NAME|ID [--json]
Examples:
sandscale workspace stat payments-dev sandscale workspace support-bundle
sandscale workspace support-bundle: A JSON file for support: the workspace, its agent, builds and logs, with tokens and secrets removed
Usage:
sandscale workspace support-bundle NAME|ID [--output FILE|-] [--logs N]
Written with mode 0600 and never over an existing file. Review it before you share it: names, ids and log lines are kept.
Examples:
sandscale workspace support-bundle payments-dev sandscale workspace ssh-cert
sandscale workspace ssh-cert: Make sure the workspace key and a fresh SSH certificate are on disk
Usage:
sandscale workspace ssh-cert NAME|ID [--json]
Prints nothing when it is run by ssh (or its output is not a terminal); at a terminal it says who the certificate is for and until when. ssh reads its key files before it runs the ProxyCommand, so config-ssh has ssh run this first (a `Match exec` line in each host's entry); you can also run it before starting another tool that reads ~/.sandscale/ssh/<id>/id_ed25519 and id_ed25519-cert.pub.
Examples:
sandscale workspace ssh-cert payments-dev
sandscale workspace ssh-cert payments-dev --json sandscale workspace ssh-proxy
sandscale workspace ssh-proxy: ssh's ProxyCommand: for tools that run their own ssh
Usage:
sandscale workspace ssh-proxy NAME|ID
Keeps a valid certificate for the workspace in ~/.sandscale/ssh/<id>/ (made once, renewed when less than 2 minutes remain), then carries the SSH bytes over Sandscale on stdin and stdout. Use it as `ProxyCommand sandscale workspace ssh-proxy NAME` with `IdentityFile ~/.sandscale/ssh/<id>/id_ed25519` and `CertificateFile ~/.sandscale/ssh/<id>/id_ed25519-cert.pub`; config-ssh writes all of that for you. A refusal is printed on stderr, with the exit codes below.
Examples:
sandscale workspace config-ssh Examples
sandscale workspace list
sandscale workspace open payments-dev
sandscale workspace ssh payments-dev -- make test Exit codes: 0 done, 1 failed, 2 usage, 3 no session, 4 refused, 5 not found, 6 conflict or precondition, 7 rate limited.
sandscale sandbox
Sandboxes
Uses your own Sandscale sign-in (sandscale login).
| Command | What it does |
|---|---|
sandbox list | Your sandboxes |
sandbox start | Start a sandbox (--options: what you may start now) |
sandbox show | One sandbox |
sandbox exec | Run a command; prints its output and exits with its exit code |
sandbox files | List, read and write files in a sandbox |
sandbox logs | The sandbox's runs, or one run's output |
sandbox stop | Stop a sandbox |
sandbox run | Send a folder, run a command, stream its output and exit with its code |
sandbox spawn | Start a sandbox, wait until it runs and open a terminal in it |
sandbox connect | A terminal in a running sandbox |
sandbox metrics | A sandbox's CPU, memory and disk use |
sandbox template | Sandbox templates: an image pinned by digest and its default size |
sandscale sandbox list
sandscale sandbox list: Your sandboxes
Usage:
sandscale sandbox list [--limit N] [--cursor C] [--json]
Examples:
sandscale sandbox list sandscale sandbox start
sandscale sandbox start: Start a sandbox (--options: what you may start now)
Usage:
sandscale sandbox start [--template ID] [--name NAME] [--ttl 1h] [--network none] [--mem MB] [--cpus N] [--label KEY=VALUE]... [--json]
sandscale sandbox start --options [--json]
Examples:
sandscale sandbox start --options
sandscale sandbox start --template python-3.12 --ttl 1h --network none sandscale sandbox show
sandscale sandbox show: One sandbox
Usage:
sandscale sandbox show ID [--json]
Examples:
sandscale sandbox show sbx_9 sandscale sandbox exec
sandscale sandbox exec: Run a command; prints its output and exits with its exit code
Usage:
sandscale sandbox exec ID [--workdir DIR] [--timeout SECONDS] [--stdin] [--json] -- COMMAND [ARGS...]
Examples:
sandscale sandbox exec sbx_9 -- python -V
sandscale sandbox exec sbx_9 --workdir /work -- make test sandscale sandbox files
sandscale sandbox files: List, read and write files in a sandbox
Usage:
sandscale sandbox files ls ID PATH [--json]
sandscale sandbox files get ID PATH [--out FILE] [--json]
sandscale sandbox files put ID PATH --from FILE [--mode 0644]
Commands:
ls List a directory
get Read a file
put Write a file
Examples:
sandscale sandbox files ls sbx_9 /work
sandscale sandbox files put sbx_9 /work/data.csv --from ./data.csv sandscale sandbox logs
sandscale sandbox logs: The sandbox's runs, or one run's output
Usage:
sandscale sandbox logs ID [--run RUN_ID] [--json]
Examples:
sandscale sandbox logs sbx_9 --run run_3 sandscale sandbox stop
sandscale sandbox stop: Stop a sandbox
Usage:
sandscale sandbox stop ID [--json]
Examples:
sandscale sandbox stop sbx_9 sandscale sandbox run
sandscale sandbox run: Send a folder, run a command, stream its output and exit with its code
Usage:
sandscale sandbox run [--sandbox ID | --template ID [--ttl 1h] [--network none] [--mem MB] [--cpus N] [--label KEY=VALUE]... [--keep]] [--sync DIR [--to /workspace] [--dry-run]] [--workdir DIR] [--timeout SECONDS] [--json] -- COMMAND [ARGS...]
Without --sandbox it starts a sandbox, waits until it runs and stops it afterwards (--keep leaves it running). --sync sends the folder first (to /workspace unless --to says otherwise) and runs the command there. It leaves out what .gitignore and a .neuralinverseignore at the top of the folder leave out, .git, node_modules and symbolic links, and never sends a secret or environment file (.env*, keys, credentials, cloud and registry tokens, Terraform state): those are listed by rule and path, never shown. --dry-run lists what would be sent and sends nothing. Ctrl+C cancels the run.
Examples:
sandscale sandbox run --sync . -- make test
sandscale sandbox run --sync . --template python-3.12 -- pytest -q
sandscale sandbox run --sync . --dry-run -- true
sandscale sandbox run --sandbox sbx_9 --sync ./app --to /workspace/app -- npm test sandscale sandbox spawn
sandscale sandbox spawn: Start a sandbox, wait until it runs and open a terminal in it
Usage:
sandscale sandbox spawn [TEMPLATE] [--name NAME] [--ttl 1h] [--network none] [--mem MB] [--cpus N] [--label KEY=VALUE]... [--no-connect] [--json]
The terminal needs Sandscale to offer one (start --options, features.terminal); without it spawn starts nothing. --no-connect starts the sandbox and waits until it runs.
Examples:
sandscale sandbox spawn python-3.12
sandscale sandbox spawn python-3.12 --ttl 2h --no-connect sandscale sandbox connect
sandscale sandbox connect: A terminal in a running sandbox
Usage:
sandscale sandbox connect ID
Needs a terminal and Sandscale to offer one in sandboxes; exits with the shell's exit code.
Examples:
sandscale sandbox connect sbx_9 sandscale sandbox metrics
sandscale sandbox metrics: A sandbox's CPU, memory and disk use
Usage:
sandscale sandbox metrics ID [--follow] [--interval 5s] [--json]
--follow prints new samples as they come (one JSON object per line with --json).
Examples:
sandscale sandbox metrics sbx_9
sandscale sandbox metrics sbx_9 --follow --interval 10s sandscale sandbox template
sandscale sandbox template: Sandbox templates: an image pinned by digest and its default size
Usage:
sandscale sandbox template init [--name NAME] [--image REF] [--file FILE] [--force] [--json]
sandscale sandbox template build [--file FILE] [--name NAME] [--version 1.0.0] [--image REF] [--cpus N] [--mem MB] [--disk MB] [--json]
sandscale sandbox template list [--json]
sandscale sandbox template delete NAME|ID [--yes] [--json]
init writes neuralinverse.sandbox.json and sends nothing. Sandscale builds no images: build and push the image yourself, set image to its reference pinned by digest (name@sha256:...), then template build registers it.
Commands:
init Write the template file in this folder (nothing is sent)
build Register the template the file (and the options) describe
list The templates you may use
delete Delete a template (by name or id); asks first unless --yes
Examples:
sandscale sandbox template init
sandscale sandbox template build
sandscale sandbox template list
sandscale sandbox template delete my-app --yes Examples
sandscale sandbox run --sync . -- make test
sandscale sandbox start --template python-3.12
sandscale sandbox exec sbx_9 -- python -V Exit codes: 0 done (exec and run: the command's code), 1 failed, 2 usage, 3 no session, 4 refused, 5 not found, 6 conflict, 7 rate limited.
sandscale build
Build hosts and lab hosts: pools, your leases, runs and their logs
Uses your own Sandscale sign-in (sandscale login). Administrators manage pools, enrolment tokens and lab hosts in the console.
| Command | What it does |
|---|---|
build pools | The pools you can see |
build leases | Your leases, newest first |
build lease | Show, create, renew or release a lease |
build runs | A lease's runs |
build logs | One run's log |
build lab-hosts | Lab hosts and their devices |
build usage | Your usage and limits |
sandscale build pools
sandscale build pools: The pools you can see
Usage:
sandscale build pools [--json] sandscale build leases
sandscale build leases: Your leases, newest first
Usage:
sandscale build leases [--state active|ended|all] [--limit N] [--json] sandscale build lease
sandscale build lease: Show, create, renew or release a lease
Usage:
sandscale build lease show LEASE [--json]
sandscale build lease create POOL [--size NAME] [--ttl 1h] [--purpose TEXT] [--repo REPO] [--json]
sandscale build lease renew LEASE [--ttl 1h] [--json]
sandscale build lease release LEASE [--json] sandscale build runs
sandscale build runs: A lease's runs
Usage:
sandscale build runs LEASE [--json] sandscale build logs
sandscale build logs: One run's log
Usage:
sandscale build logs LEASE RUN sandscale build lab-hosts
sandscale build lab-hosts: Lab hosts and their devices
Usage:
sandscale build lab-hosts [--json]
sandscale build lab-hosts show HOST [--json]
sandscale build lab-hosts devices HOST [--json] sandscale build usage
sandscale build usage: Your usage and limits
Usage:
sandscale build usage [--json] Examples
sandscale build pools
sandscale build lease create POOL --size medium --ttl 2h
sandscale build logs LEASE RUN Exit codes: 0 done, 1 failed, 2 usage, 3 not signed in, 4 refused, 5 not found, 6 conflict or precondition, 7 rate limited.
sandscale vault
Sandscale Vault: KV secrets, policies, leases, transit, mounts and audit devices
Uses your own Sandscale sign-in (sandscale login). Values are printed only with --reveal to a terminal and typed without echo. Running a program with secrets (vault run) is not in the Sandscale CLI.
| Command | What it does |
|---|---|
vault kv | KV version 2 secrets |
vault policy | Vault policies |
vault lease | Your leases |
vault transit | Encrypt and decrypt |
vault mounts | The secrets engines you can see |
vault audit | The vault's audit devices |
sandscale vault kv
sandscale vault kv: KV version 2 secrets
Usage:
sandscale vault kv get [--mount M] PATH [--field F] [--version N] [--reveal] [--json]
sandscale vault kv put [--mount M] [--cas N] PATH FIELD=- | FIELD=@FILE ...
sandscale vault kv list|delete|undelete|destroy [--mount M] [--versions N,...] [--yes] PATH
sandscale vault kv metadata get|put|delete [--mount M] [--yes] PATH sandscale vault policy
sandscale vault policy: Vault policies
Usage:
sandscale vault policy list [--json]
sandscale vault policy read NAME [--json]
sandscale vault policy write NAME FILE|- sandscale vault lease
sandscale vault lease: Your leases
Usage:
sandscale vault lease list [--prefix P]
sandscale vault lease lookup ID
sandscale vault lease renew ID [--increment DUR]
sandscale vault lease revoke [--yes] ID sandscale vault transit
sandscale vault transit: Encrypt and decrypt
Usage:
sandscale vault transit encrypt [--mount M] [--context B64] KEY
sandscale vault transit decrypt [--mount M] [--context B64] [--base64] --reveal KEY CIPHERTEXT sandscale vault mounts
sandscale vault mounts: The secrets engines you can see
Usage:
sandscale vault mounts [--json] sandscale vault audit
sandscale vault audit: The vault's audit devices
Usage:
sandscale vault audit list [--json] Examples
sandscale vault kv get app/db --field password --reveal
sandscale vault mounts sandscale logs
Logs of a workspace, a sandbox or a build host run
| Command | What it does |
|---|---|
logs workspace | The workspace agent's or a build's logs |
logs sandbox | A sandbox's runs, or one run's output |
logs build | One build host run's log |
sandscale logs workspace
sandscale logs workspace: The workspace agent's or a build's logs
Usage:
sandscale logs workspace NAME|ID [--build ID|latest] [--follow] [--after N] [--limit N] [--json] sandscale logs sandbox
sandscale logs sandbox: A sandbox's runs, or one run's output
Usage:
sandscale logs sandbox ID [--run RUN_ID] [--json] sandscale logs build
sandscale logs build: One build host run's log
Usage:
sandscale logs build LEASE RUN Examples
sandscale logs workspace payments-dev --follow
sandscale logs sandbox sbx_9 --run run_3 sandscale mcp
An MCP server (stdio) with your workspaces, sandboxes and build hosts as tools
sandscale mcp: An MCP server (stdio) with your workspaces, sandboxes and build hosts as tools
Usage:
sandscale mcp [serve]
Uses your own Sandscale sign-in (sandscale login). Add it to a coding tool as a stdio server: command "sandscale", arguments ["mcp"]. Vault values are never offered to a model.
Examples:
sandscale mcp sandscale help
Help for a command
sandscale help: Help for a command
Usage:
sandscale help [COMMAND [SUBCOMMAND]] sandscale version
Print the version
sandscale version: Print the version
Usage:
sandscale version This page is generated from the sandscale CLI's command registry (src/sandscale/commands.ts). Do not edit it by hand.