keys

The keys command manages org API keys, the credential used for CI, headless agents, and the hosted MCP server. It talks to the same endpoints as the dashboard’s Settings → API Keys page.

Keys belong to one organization

A key is minted for exactly one org and spends that org’s credits. If your account belongs to more than one org, create will not choose for you: it lists your orgs and stops until you pass --org. Run squirrel auth whoami to see which org your cloud runs currently act for.

squirrel keys create --org acme

An audit signed in with a key is billed differently from a logged-in one: no audit base or page charge, and its external links are checked on the runner for free. See What an API-key audit costs.

--org takes an org slug (the name in your dashboard URL) or its id. It is an exact match, never a prefix, so a typo is refused rather than resolved to the wrong org.

Subcommands

• create - Mint a new key
• list - List keys for your org
• revoke - Revoke a key by prefix or id

create

Mint a new org API key. The plaintext token is shown once, copy it before you close the terminal.

Usage

squirrel keys create [options]

Options

Example

squirrel keys create --name "CI" --org acme --scopes audits:write,audits:read,credits:read

✓ Created API key CI (sq_ab12cd…)
  Org: acme (Acme Inc) org_2xK9vQ
  Scopes: audits:write, audits:read, credits:read
  Expires: never

Save this key now (it will not be shown again):
  export SQUIRRELSCAN_API_KEY=sq_xxxxxxxxxxxx

--shell

--shell shows the exact line and target file, asks for confirmation, then appends (never overwrites), with a trailing # added by squirrel keys create comment so it’s easy to find later:

squirrel keys create --shell

About to append to /Users/you/.zshenv:
  export SQUIRRELSCAN_API_KEY=sq_ab12cd…  # added by squirrel keys create
Append this line? [y/N]

zsh prefers ~/.zshenv (sourced for every invocation, not just interactive shells) when it exists, falling back to ~/.zshrc. Requires an interactive terminal: in CI or a non-TTY shell, copy the printed export line manually instead.

More than one organization

Without --org, a multi-org account gets the list and no key:

squirrel keys create

Error: You belong to 2 organizations, so this command will not pick one for you. Re-run with --org <slug|id>.
Organizations:
  acme  Acme Inc [active]
    id: org_2xK9vQ
  acme-ci  Acme CI (internal)
    id: org_7pL3mR

[active] marks the org your cloud audits already spend from. Nothing is minted on this path.

list

List API keys, grouped by organization. Every org you belong to is listed, so a key is never shown without the org it spends from.

Usage

squirrel keys list [options]

Options

Example

squirrel keys list

acme Acme Inc  org_2xK9vQ
  sq_ab12cd…  CI  active
    Scopes: audits:write, audits:read, credits:read
    Created: Jun 1, 2026  Last used: Jul 3, 2026

acme-ci Acme CI (internal)  org_7pL3mR
  (no keys)

With --json, stdout is a flat array in which each key carries orgId, orgSlug, and orgName.

Listing keys needs the owner or admin role in that org. An org where you are a plain member is listed with the reason its keys could not be read, rather than failing the whole command. Under --json that reason is written to stderr as a Warning: line, so the array on stdout is never silently short.

revoke

Revoke a key immediately by its prefix (as shown by list) or full id.

Usage

squirrel keys revoke <prefix-or-id> [options]

Options

Example

squirrel keys revoke sq_ab12cd

About to revoke CI (sq_ab12cd…) from acme (Acme Inc) org_2xK9vQ.
Continue? [y/N] y
✓ Revoked CI (sq_ab12cd…) from acme

The prefix is searched across every org you belong to, so you don’t need to know which org a key lives in. A prefix that matches more than one active key errors instead of guessing: use a longer prefix, the full id, or --org to narrow the search.

If any org’s keys could not be read, a prefix match is refused rather than resolved against a partial search: a key in the org that failed to list could match the same prefix. A full key id is unique account-wide and still works.

Related

• Authentication - token types, scopes, and precedence
• auth - log in first; keys requires a login session
• Hosted MCP - the main consumer of a minted key for agents