CLI Authentication
The CLI can authenticate in two ways. Pick whichever fits:
| Method | Who can use it | Best for |
|---|---|---|
| Sign in with your browser (OAuth) | Every user of a company whose plan includes the External API | Your own machine: nothing to create or copy, and it works with the workspaces you already have access to |
| API key | Admins create keys under Settings → API Keys (API Keys) | CI, scripts and servers, or when one key should be shared by a team |
Both reach the same REST API and give the same results. Both need a plan that includes the External API; on other plans the contacts and metrics commands fail with exit code 4 (forbidden). An API key's permissions (crm:read, crm:write, metrics:read) decide which commands work; signing in gives you the full set.
Sign in with your browser
perspective auth login
The CLI opens your browser on the Perspective sign-in page (the same OAuth flow the MCP server uses), waits for you to finish, and stores the resulting tokens. It refreshes them by itself, so you only sign in once.
If the browser does not open (SSH session, container), the sign-in URL is printed, and --no-open prints it without trying:
perspective auth login --no-open
Open the URL in any browser on the same machine; the sign-in completes back in the terminal.
Use an API key
perspective auth login --method api-key # prompts for the key, input hidden
In a script, pipe it in instead, so it doesn't end up in your shell history:
printf %s "$PERSPECTIVE_API_KEY" | perspective auth login
A piped key, or --api-key <key>, selects the API-key method by itself. The CLI validates the key with one read request before storing it.
Check and clear credentials
perspective auth status # method (oauth | api-key), where it comes from, when a sign-in expires; no network calls
perspective auth logout # delete the stored credentials
auth status never prints a key or token in full.
CI and automation
Skip the stored file and pass an API key through the environment:
export PERSPECTIVE_API_KEY=…
Precedence, highest first: the --api-key flag, the PERSPECTIVE_API_KEY environment variable, the stored credentials (an API key or a sign-in — auth login keeps one at a time).
Where credentials are stored
~/.config/perspective/credentials.json (or $XDG_CONFIG_HOME/perspective/, or $PERSPECTIVE_CONFIG_DIR), readable only by your user (mode 0600). Treat it like a password: a sign-in's refresh token keeps working until you run perspective auth logout.