Login and Logout

Authenticate the CLI against Shelve and manage stored credentials.

Login

shelve login

The CLI prompts for a token. Create one from the Shelve dashboard at app.shelve.cloud/user/tokens, then paste it into the prompt. Tokens are scopeable, expiring, and IP-bound — 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). 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.

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.

Me

shelve me

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

Logout

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:

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.

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, …).

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.