# Login and Logout

> Authenticate the CLI against Shelve and manage stored credentials.

## Login

```bash [terminal]
shelve login
```

The CLI prompts for a token. Create one from the Shelve dashboard at [app.shelve.cloud/user/tokens](https://app.shelve.cloud/user/tokens), then paste it into the prompt. Tokens are [scopeable, expiring, and IP-bound](/docs/core-features/tokens) — prefer a narrowly-scoped token to your account-wide default.

### Where the token is stored

1. **OS keychain first** — Keychain on macOS, Credential Vault on Windows, Secret Service / GNOME Keyring / KWallet on Linux (via [`@napi-rs/keyring`](https://github.com/napi-rs/keyring)). The value is encrypted at rest and gated by the OS session.
2. **XDG file fallback** — if the keychain is unavailable (headless CI containers, missing D-Bus on Linux, …) the CLI writes to `$XDG_CONFIG_HOME/.shelve` (typically `~/.config/.shelve`) with mode `0600`. A warning is printed so you know you are on the fallback path.

<callout type="info">

Older CLI versions wrote credentials to `~/.shelve`. The first `login` / `logout` / `pull` you run with a v5 CLI will migrate the legacy file into the XDG location and delete the original.

</callout>

### Me

```bash [terminal]
shelve me
```

Prints the account the current token is attached to, the Shelve instance URL, and which storage backend holds the token.

## Logout

```bash [terminal]
shelve logout
```

Removes the token from the keychain (if present) and clears the XDG config. Subsequent CLI commands refuse to run until you log in again.

## Non-interactive environments

In CI, a container, or any automation flow, skip `shelve login` entirely and pass the token via an environment variable:

```bash [terminal]
SHELVE_TOKEN="$SHELVE_TOKEN" shelve run -- pnpm test
```

The CLI reads `SHELVE_TOKEN` before consulting the keychain or the XDG file. Pair it with a scoped, expiring token for least-privilege CI access.

<callout type="warning">

Never commit `SHELVE_TOKEN` to git. Use your CI provider's secrets UI or a runtime secret store (GitHub Actions secrets, Vercel project env vars, …).

</callout>

## Multiple accounts

Only one account per machine is supported at a time. To switch accounts, `shelve logout` and `shelve login` again with the new token.