Install the CLI and sign in

The CLI needs Node.js 22.12 or later. Run it without installing:

npx spacecontext --help

or install it globally:

npm install -g spacecontext
spacecontext --version

Sign in

spacecontext login            # a live key
spacecontext login --test     # a test key: free, the demo space

The terminal shows a code and opens the console (sign in with Apple, Google, GitHub or your email if you are not yet). Type the code there, check what is asking, choose what the key may do, and approve: the terminal receives its key and saves it in ~/.config/spacecontext/config.json (or $XDG_CONFIG_HOME/spacecontext/), readable by your user only. The key never passes through the browser, and the console never sees your terminal.

A live key that can scan (scans:write) needs a card on file. If your account has none, the console tells you so instead of approving: add one under Billing → Add a card (nothing is charged) and approve again, or approve a key without scans:write. The terminal says this while it waits. login --test never needs a card.

Approve only a code you are looking at in your own terminal: the name shown in the console is what the terminal said about itself. The code is never carried in a link for that reason. --no-browser only prints the link.

Already have a key? spacecontext login --key - asks for it without echoing it, checks it with the API and saves it. Prefer it, or the code above, to --key sc_…: that works too, but leaves the key in your shell history.

spacecontext whoami      # account, the key in use (masked), its mode and scopes
spacecontext logout      # forget it

Where the key comes from

The CLI uses the first of:

1. --api-key sc_… on the command line;
2. the SPACECONTEXT_API_KEY environment variable (handy in CI; empty counts as unset);
3. the key saved by login.

--base-url and SPACECONTEXT_BASE_URL point the CLI at another API base. A base URL saved by login --base-url … is used only together with the key saved with it, so a key from the environment never goes to a URL meant for another key.

Output for scripts

Every command accepts --json and prints the API’s JSON on standard output; progress goes to standard error. Exit codes: 0 success, 1 the request failed, 2 wrong usage. Errors print the API’s code and request id:

✗ Error [INSUFFICIENT_FUNDS]: The wallet does not cover this scan (request 8f0c2b9e-…)
  › Top up the balance in the console: https://spacecontext.app/developers/console/billing/
  › `spacecontext wallet` shows the balance and the price of a scan

Every error ends with what to do next: the console page to open, the command to run, or the variable to fix.

At a terminal the CLI uses colours and a live status line. When the output is piped or redirected it prints plain lines, and NO_COLOR=1 (or TERM=dumb) turns colours off. --json output is never styled, and with --json standard error carries only errors (and the sign-in code of login).

Next: the commands.