auth

The auth command manages authentication for cloud features - cloud rules, browser rendering, and publishing reports. Every account gets 500 free credits each month, no card required.

There are two ways to authenticate:

• squirrel auth login — interactive browser sign-in, tied to your user. Best for local development.
• SQUIRRELSCAN_API_KEY env var — a long-lived, org-scoped API key. Best for CI, headless agents, and automation. See API token.

Subcommands

• login - Sign in to squirrelscan
• logout - Sign out and revoke token
• status / whoami - Show the active credential (source, scopes, org)
• squirrel keys - Mint, list, and revoke org API keys without leaving the terminal

API token (CI / headless)

For CI and headless use, set the SQUIRRELSCAN_API_KEY environment variable to an org API key. Mint one from the terminal with squirrel keys create, or from the dashboard. No squirrel auth login is required at run time — the token is read straight from the environment.

SQUIRRELSCAN_API_KEY=sq_xxxxxxxxxxxx squirrel audit https://example.com

API keys are org-scoped (audits debit the org’s credit pool) and carry scopes. They are sent as Authorization: Bearer <token>, the same transport as a login session — the API tells them apart by prefix.

Minting a key from the CLI

squirrel auth login          # once, interactively
squirrel keys create --shell # mints a key and offers to append the export line

See squirrel keys for list and revoke too.

Credential precedence

When the CLI needs to authenticate a cloud call it resolves one credential, highest priority first:

1. SQUIRRELSCAN_API_KEY (or its back-compat alias SQUIRREL_API_TOKEN, checked only when the preferred var is unset) — authoritative. It overrides a logged-in session, and is fail-closed: if the token is invalid (revoked, expired, or minted for a different environment) the CLI errors — it does not silently fall back to your login session. This keeps CI predictable and avoids the “I exported a token but it used my personal session” surprise (the same convention as gh, the Stripe CLI, and AWS).
2. Logged-in session (squirrel auth login) — used only when neither env var is set (or non-empty).
3. Unauthenticated — local / deterministic-only audits.

The env token is never written to ~/.squirrel/settings.json. An empty or whitespace-only value is treated as unset (it falls through to the alias, then the login session).

Environment-aware prefixes

Keys carry an environment segment so a dev key can’t accidentally hit production (and vice-versa) — the API rejects cross-environment keys with a clear error.

Scopes

API keys carry per-resource scopes (resource:action). A key is only allowed to call endpoints covered by its scopes; a request outside its scopes returns a clear error naming the missing scope.

Login sessions are unscoped (full access) — scopes only apply to API keys.

GitHub Actions

- name: Audit
  env:
    SQUIRRELSCAN_API_KEY: ${{ secrets.SQUIRRELSCAN_API_KEY }}
  run: squirrel audit https://example.com --yes

Store the key as a repository or organization secret — never commit it. A CI preset key (audits + credits read) is enough for most pipelines.

login

Authenticate with squirrelscan using device authorization flow.

Usage

squirrel auth login [options]

Options

Example

squirrel auth login

Opens browser for authentication. After completing login:

✓ Authenticated as you@example.com
  Device: macbook-pro
  Expires: Feb 2, 2027

Troubleshooting

Couldn't reach the auth server … — the API was unreachable (it’s down, or you’re pointed at a local/dev server that isn’t running). The error names the server it tried. To target production, unset or set the override:

SQUIRREL_API_SERVER=https://api.squirrelscan.com squirrel auth login

Session expired / cloud unavailable during an audit — if your login token has expired (or the API can’t be reached), squirrel audit keeps working with local checks only and prints the reason on the Account line. Cloud features (renders, AI summary, tech detection) are skipped cleanly — nothing fails. In an interactive terminal you’ll be asked whether to continue local-only; agents, CI, piped output and --yes proceed automatically. Run squirrel auth login to restore cloud features.

SQUIRRELSCAN_API_KEY was rejected … — an API token is fail-closed: when set, an invalid token (revoked, expired, or wrong environment) errors the command rather than degrading to local-only. The message names whichever env var you actually set (SQUIRRELSCAN_API_KEY or the SQUIRREL_API_TOKEN alias). Fix or rotate the key with squirrel keys create or the dashboard, or unset it to use your login session instead.

logout

Sign out and revoke the current authentication token.

Usage

squirrel auth logout

Example

squirrel auth logout

✓ Signed out successfully

status

Show the active credential — its source (login session vs env var — SQUIRRELSCAN_API_KEY or the SQUIRREL_API_TOKEN alias), and, for API keys, the org and granted scopes.

Usage

squirrel auth status [options]

Options

Example

Logged-in session:

squirrel auth status

Authenticated as you@example.com
  Source: logged-in session
  Device: macbook-pro
  Expires: Feb 2, 2027
  Credits: 950

With an API key via SQUIRRELSCAN_API_KEY (note the Source line and the scopes):

Authenticated as ci@acme.com
  Source: SQUIRRELSCAN_API_KEY env var
  Org: Acme Inc
  Key: CI – production
  Scopes: audits:write, credits:read
  Key env: production
  Credits: 12,400

When an env token shadows a logged-in session, status notes which session is being overridden.

JSON output:

squirrel auth status --json

{
  "authenticated": true,
  "source": "env",
  "user": { "id": "u_123", "email": "ci@acme.com", "name": "CI Bot" },
  "token": { "deviceName": null, "expiresAt": null },
  "apiKey": {
    "name": "CI – production",
    "scopes": ["audits:write", "credits:read"],
    "keyEnv": "production"
  },
  "org": { "id": "org_123", "name": "Acme Inc" }
}

whoami

Alias for status — the conventional name for “who am I authenticated as”. Same output and --json flag.

squirrel auth whoami

Related

• squirrel keys - Mint, list, and revoke org API keys
• Dashboard - Manage reports online
• report —publish - Publish reports