Reference

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).

CommandWhat it does
workspace listYour workspaces
workspace showOne workspace
workspace createCreate a workspace from a template
workspace openStart it when stopped, wait until it runs, then ssh (or a terminal); with --ide, open it in an editor
workspace sshThe system ssh through Sandscale, with a short-lived certificate and a checked host key
workspace logsThe workspace agent's or a build's logs
workspace stopStop a workspace
workspace restartStop it, wait until it stopped, then start it
workspace updateRebuild it on its template's active version
workspace renameRename a workspace (your own sign-in)
workspace deleteDelete a workspace and its disks (your own sign-in; Sandscale may ask you to confirm it is you)
workspace port-forwardForward local ports to a workspace's ports (until Ctrl+C)
workspace scheduleShow or set when it starts, stops after a start, and stops when idle
workspace templatesTemplates you may create workspaces from
workspace dotfilesYour dotfiles repository, applied to workspaces (your own sign-in)
workspace pingRound trips to Sandscale and the state of the workspace agent
workspace statCPU, memory and disk the workspace agent last reported
workspace support-bundleA JSON file for support: the workspace, its agent, builds and logs, with tokens and secrets removed
workspace ssh-certMake sure the workspace key and a fresh SSH certificate are on disk
workspace ssh-proxyssh'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).

CommandWhat it does
sandbox listYour sandboxes
sandbox startStart a sandbox (--options: what you may start now)
sandbox showOne sandbox
sandbox execRun a command; prints its output and exits with its exit code
sandbox filesList, read and write files in a sandbox
sandbox logsThe sandbox's runs, or one run's output
sandbox stopStop a sandbox
sandbox runSend a folder, run a command, stream its output and exit with its code
sandbox spawnStart a sandbox, wait until it runs and open a terminal in it
sandbox connectA terminal in a running sandbox
sandbox metricsA sandbox's CPU, memory and disk use
sandbox templateSandbox 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.

CommandWhat it does
build poolsThe pools you can see
build leasesYour leases, newest first
build leaseShow, create, renew or release a lease
build runsA lease's runs
build logsOne run's log
build lab-hostsLab hosts and their devices
build usageYour 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.

CommandWhat it does
vault kvKV version 2 secrets
vault policyVault policies
vault leaseYour leases
vault transitEncrypt and decrypt
vault mountsThe secrets engines you can see
vault auditThe 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

CommandWhat it does
logs workspaceThe workspace agent's or a build's logs
logs sandboxA sandbox's runs, or one run's output
logs buildOne 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.