# The CLI

**Spinbox is experimental: APIs change and data may be lost.** What is built and what proves it is on [Status](https://docs.spinbox.dev/reference/status.md); what Spinbox does not do is on [Limitations](https://docs.spinbox.dev/overview/limitations.md).

> Install the spin CLI, sign in, use profiles for several installations, and get JSON output for scripts.

`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](https://docs.spinbox.dev/reference/cli.md).

## 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:

```bash
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.

## Sign in

```bash
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:

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

## Several installations

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

```bash
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. 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.

```bash
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.
