spade login

The spade login command authenticates the CLI to a Spade server using the OAuth 2.0 Device Authorization Flow (RFC 8628). The CLI displays a short code in the terminal; you open a verification URL in any browser — on the same machine or a different one — and enter the code there. There is no local callback listener: the CLI never opens a port or waits for a redirect, it simply polls the server until you've approved the code.

Usage🔗

spade login --server <url>
spade logout

spade logout takes no arguments.

The --server flag🔗

spade login requires a server URL. It is resolved in this order:

  1. The --server flag
  2. The SPADE_SERVER environment variable
  3. The server key in ~/.spade.yaml

If none of these is set, spade login fails immediately:

Error: server URL required: set --server, SPADE_SERVER, or 'server' in ~/.spade.yaml

What it does🔗

1. Request a device code🔗

The CLI posts to <server>/api/auth/device/code with a fixed client ID (spade-cli). The server responds with a device_code, a user_code, a verification_uri, an expiry, and a polling interval.

2. Display the code🔗

To authorize this device:

  1. Open:  https://spade.example.com/device
  2. Enter: WDJB-MJHT

3. Poll for authorization🔗

The CLI polls <server>/api/auth/device/token at the server-specified interval until one of:

  • Success — the server returns an access token.
  • authorization_pending — keep polling.
  • slow_down — back off by increasing the poll interval.
  • expired_token — the code expired before it was approved; run spade login again.
  • access_denied — the authorization request was rejected.

4. Store the session🔗

On success, the CLI writes the token, the server URL, and the issue time to ~/.spade/auth/credentials.json (mode 0600, readable only by the owning user).

Logging out🔗

spade logout

Removes ~/.spade/auth/credentials.json. Commands that require authentication will report that you're not logged in and prompt you to run spade login again.

Who needs this🔗

spade login is a developer-facing concern, used today by the spade data subcommands (upload, download, list), which load the stored credentials to authenticate to the server. spade upload (packaging a collection locally) does not require a login session, since it doesn't talk to a server yet.

Workers do not use spade login. A worker fleet authenticates with its own service-token mechanism, unrelated to any developer's stored credentials.

Example🔗

spade login --server https://spade.example.com
To authorize this device:

  1. Open:  https://spade.example.com/device
  2. Enter: WDJB-MJHT

Waiting for authorization... |
Logged in successfully.
spade logout
Logged out.

See also🔗

  • spade data for the commands that use the stored session today
  • spade secret for local secret management, which does not require a login session