---
title: "Install the CLI and sign in"
description: "Install the spacecontext CLI with npx or npm (Node.js 22.12 or later), sign in with a code approved in the console, and see which key it uses."
source_url: https://spacecontext.app/developers/docs/cli/install/
---

# Install the CLI and sign in

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

```bash
npx spacecontext --help
```

or install it globally:

```bash
npm install -g spacecontext
spacecontext --version
```

## Sign in

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

The terminal shows a code and opens the [console](https://spacecontext.app/developers/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.

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

```text
✗ 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](https://spacecontext.app/developers/docs/cli/commands.md).