Login

sandscape login authorizes your machine once using the device-authorization flow (RFC 8628). Run it and follow the prompt:

sandscape login

It prints a verification URL and a short code. Open the URL, sign in, and approve the code; the CLI waits, then stores a scoped, revocable token in your home config. The token is never printed. You can revoke it anytime from the Sandscape account UI.

That's all you need for interactive use — the rest of this page covers the automated flow a coding agent uses.

Check first — are you already authorized?

The token is stored per machine, so you rarely need to log in twice. To check without starting a new login, run any command — for example:

sandscape list --json

Exit code 0 means you're already authorized (and you get your project list back); exit 1 with a "Not authorized" message means it's time to log in.

Automating login from a coding agent

Because login blocks until you approve in the browser, an agent runs it in the background and reads its events from a file instead of waiting in the foreground:

LOG="${TMPDIR:-/tmp}/sandscape-login.jsonl"
npx -y @sandscape/cli@latest login --json > "$LOG" 2>&1 &
LOGIN_PID=$!

1. It polls $LOG for the first line — a {"event":"verification", …} object — and shows you verification_uri_complete as a link to open and approve.
2. It then waits for the process. Exit 0 → the last line is {"event":"authorized", …} and you're in. Exit 1 → the last line is {"event":"error", …}, and it retries.

--json event stream

sandscape login --json emits a line-delimited event stream:

{"event":"verification","verification_uri":"https://…/device","user_code":"ABCD-EFGH","verification_uri_complete":"https://…/device?code=ABCD-EFGH","expires_in":900,"interval":5}
{"event":"authorized","scopes":["cli"]}

On failure the final line is {"event":"error","error":"device_flow","message":"…"} and the process exits 1. The token is never emitted.

Logout

sandscape logout removes the stored credentials from your machine. To revoke the token itself, use the Sandscape account UI.