The CLI
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.
Install
Section titled “Install”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:
oras pull ghcr.io/spin-stack/spin-release:v20261027.01-spin-linux-amd64spin 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.
Sign in
Section titled “Sign in”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:
spin login --endpoint https://app.<domain> --token-stdin < key.txtSeveral installations
Section titled “Several installations”A profile is a named sign-in. Every command takes --profile, and SPIN_PROFILE sets it for
a shell:
spin login --profile work --endpoint https://app.work.example.comspin --profile work workspace listEnvironment
Section titled “Environment”| Variable | What it does |
|---|---|
SPIN_ENDPOINT | The installation to talk to, instead of the profile’s |
SPIN_TOKEN | An API key to use instead of a login. No config file is needed. |
SPIN_PROFILE | The profile to use when --profile is not given |
SPIN_CA_CERT | A CA certificate to trust for the endpoint, for an installation behind a private CA |
Output for scripts
Section titled “Output for scripts”-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.
spin -o json workspace get api | jq .Names and ids
Section titled “Names and ids”Every command that takes a workspace takes its name or its id.
Waiting
Section titled “Waiting”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.

