Sign in and out — Stackbone

The two commands on this page write and remove the same file. stackbone login writes the session to ~/.stackbone/credentials.json and stackbone logout removes it again. Nothing else on disk holds it. Both wrap their --json output in the shared { "schema_version": 1, ... } envelope and follow the common exit codes.

Authenticate the CLI via the device-code flow (RFC 8628). Stores the session in ~/.stackbone/credentials.json (chmod 600). The CLI files the session under the control plane it signed in to, which is the one this directory resolves to. Point a single command somewhere else with STACKBONE_API_URL and you get a second session next to the first.

The command prints a short user code and a verification URL, then waits until you approve the request. It opens the URL for you unless you pass --no-browser or the environment looks headless. The code expires on its own. A login you deny, or never approve, ends with exit code 2.

Note

The command prints the code box in human mode only. With --json it emits one payload when the flow finishes and nothing before it. Run --json login only where the browser can open by itself.

Flag	Type	Description
`--no-browser`	boolean	Print the verification URL + code instead of opening the browser. Auto-detected when `CI`, `SSH_CLIENT`, or `SSH_TTY` is set.

JSON payload

{
  "schema_version": 1,
  "user": { "id": "...", "email": "..." },
  "control_plane_url": "https://api.stackbone.ai",
  "expires_at": "2026-...",
}

Exit codes: 0 ok, 2 auth, 1 generic.

Once you are signed in, stackbone whoami shows the user and the organization the session points at.

Every other command resolves its own control plane first and reads the session filed under that URL. When there is none, the refusal names that URL: No session for http://localhost:3790. An expired session reads Session for <url> expired. Both exit 2. Run stackbone login from the same directory, or with the same STACKBONE_API_URL, so the new session lands under the URL that was missing one.

stackbone logout

Revoke the session for this control plane and drop it from disk. No flags.

The credentials file holds one session per control plane you signed in to. logout acts on the one this directory resolves to, which is the same URL every other command targets. It revokes that session on that server and removes it from the file. The payload names it in control_plane_url. Every other environment keeps its session and its active organization. The CLI deletes the file only when the last session goes.

Server-side revocation is best effort. A network failure does not stop the CLI from clearing the local session, so this machine still ends up signed out.

JSON payload

{
  "schema_version": 1,
  "control_plane_url": "https://api.stackbone.ai",
  "previous_user": { "id": "...", "email": "..." } /* or null */,
}

Exit codes: 0 ok, 1 generic. Running logout with no session is not an error: the payload carries "previous_user": null.