Skip to content
Spinbox is experimental: APIs change and data may be lost. Status lists what is built and what proves it.

The CLI

View Markdown

spin is one binary. It does everything the dashboard does for a user, and the administration of runners and storage for an administrator. Every command is listed, with its own help, in the CLI reference.

Each release publishes spin-linux-amd64, spin-linux-arm64, spin-darwin-arm64 and spin-darwin-amd64. Download the one for your machine, make it executable and put it on your PATH as spin. Each is also in the release’s public package, under a tag of its own:

Terminal window
oras pull ghcr.io/spin-stack/spin-release:v20261027.01-spin-linux-amd64

spin version prints the release it was built from, and the CLI says it on every request. An installation refuses a CLI of any other release, and says which it runs. A CLI behind it replaces itself with that release and runs the command again; spin update does the same when asked.

Terminal window
spin login --endpoint https://app.<domain>

The CLI prints a URL and a code, and opens the URL in your browser when it can. Sign in there, from this machine or any other, and enter the code; the CLI waits until you have, then keeps the session in ~/.spin/config.yaml. Nothing listens on your machine while it waits, and --no-browser leaves opening the URL to you. spin whoami shows who you are, and spin logout forgets the token.

For a machine with no browser, create an API key in the dashboard (Settings → API Keys) and use it instead, read from standard input and never an argument:

Terminal window
spin login --endpoint https://app.<domain> --token-stdin < key.txt

A profile is a named sign-in. Every command takes --profile, and SPIN_PROFILE sets it for a shell:

Terminal window
spin login --profile work --endpoint https://app.work.example.com
spin --profile work workspace list
VariableWhat it does
SPIN_ENDPOINTThe installation to talk to, instead of the profile’s
SPIN_TOKENAn API key to use instead of a login. No config file is needed.
SPIN_PROFILEThe profile to use when --profile is not given
SPIN_CA_CERTA CA certificate to trust for the endpoint, for an installation behind a private CA

-o json prints one JSON document of what the API answered, and no prose. A command that fails prints one too, in the answer’s place: {"error": {"code", "message", "action"}}, where code is what a script decides on and action what a person would do next. The exit status says whether the command succeeded.

Terminal window
spin -o json workspace get api | jq .

Every command that takes a workspace takes its name or its id.

create, start and stop take --wait, which returns once the workspace is where you asked it to be, and --timeout for how long to wait. spin ssh, spin exec and spin code take --start to start a stopped workspace first.

Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.