Authentication

The Copera CLI signs you in once and then runs every command as you. This page covers the token types, the login flows, and how the CLI decides which credential to use when several are available.

Token types

Copera issues two kinds of tokens:

• Personal Access Token (cp_pat_...) — tied to your user account. Required for docs, drive, notifications, and workspace-user commands. Works for everything else too, so when in doubt, use a PAT.
• Integration API Key (cp_key_...) — tied to an integration, not a user. Works for boards and channels only.

tip

Docs and drive operations always require a Personal Access Token with the appropriate workspace permissions. If you see an auth error on copera docs ... or copera drive ..., double-check that you're using a cp_pat_... token.

Login modes

Command	When to use it
copera auth login	You want the guided browser flow. The CLI prints a URL, opens your browser when possible, and accepts the token you paste back.
copera auth login --token=<value>	You already have a token and want to save it directly without going through the browser.
copera auth login --token	You already have a token and want a masked paste prompt — no browser, but the token never appears in your shell history.

Once logged in, your token is stored in ~/.copera.toml and used for every subsequent command.

Sign-out

copera auth logout

This removes the stored credential. You can run copera auth login again at any time.

Inspect the current session

copera auth status     # Show the active profile and where the token came from
copera auth whoami     # Show who the token belongs to

copera auth status is especially useful when something behaves unexpectedly — it tells you whether the CLI picked up a token from your environment, a project config file, or your home directory.

Token resolution order

When you run a command, the CLI looks for a token in this order — the first one it finds wins:

Priority	Source	Example
1	Environment variable	COPERA_CLI_AUTH_TOKEN=cp_pat_xxx
2	--token flag on the command	copera boards list --token cp_pat_xxx
3	.copera.local.toml in the current directory	Project-local, git-ignored token
4	.copera.toml in the current directory	Shared project defaults
5	~/.copera.toml	User-level fallback

This is intentional:

• CI and agents can override everything else by setting COPERA_CLI_AUTH_TOKEN.
• Per-project tokens live in .copera.local.toml, which should be added to .gitignore.
• Shared project defaults (like a default board_id and table_id, with no token) live in .copera.toml, safe to commit.
• Your personal token sits in ~/.copera.toml for everything else.

Where do I get a token?

Generate a token from the Copera web app:

1. Open the workspace you want to access.
2. Go to Settings → Personal Access Tokens (for cp_pat_...) or Settings → Integrations (for cp_key_...).
3. Create a token, copy it, and paste it into the CLI prompt.

For more on what each token type can do, see the Copera authentication guide.