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

Each release publishes spin-linux-amd64 and spin-darwin-arm64. Download the one for your machine, make it executable and put it on your PATH as spin. The Linux build is also in the release’s public package:

oras pull ghcr.io/spin-stack/spin-release:v20261019.02-spin-linux-amd64

spin version prints the release it was built from. Use a CLI of the installation’s release or close to it.

Sign in

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

The CLI shows a code and opens your browser at the dashboard, where you approve it. It then keeps a session token in ~/.spin/config.yaml. 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:

spin login --endpoint https://app.<domain> --token <api-key>

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.com
spin --profile work workspace list

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

-o json prints one JSON document of what the API answered, and no prose. Errors still go to standard error, and the exit status says whether the command succeeded.

spin -o json workspace get api | jq .

Names and ids

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

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.