Skip to main content

CLI Authentication

The CLI can authenticate in two ways. Pick whichever fits:

MethodWho can use itBest for
Sign in with your browser (OAuth)Every user of a company whose plan includes the External APIYour own machine: nothing to create or copy, and it works with the workspaces you already have access to
API keyAdmins 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.