auth

Authenticate with squirrelscan for cloud features and publishing

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 login, 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 - Log 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, and 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:

SQUIRRELSCAN_API_KEY (or its back-compat alias SQUIRREL_API_TOKEN, checked only when the preferred var is unset) is 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, and 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).
Logged-in session (squirrel auth login), used only when neither env var is set (or non-empty).
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.

Prefix	Environment
`sq_…`	production
`sq_dev_…`	development
`sqcli_…`	legacy user login token (browser flow)

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.

Scope	Grants
`audits:write`	Run audits, submit cloud renders
`audits:read`	Read published reports
`credits:read`	Read credit balance + ledger
`org:read`	Read org details
`org:write`	Manage org (invites, settings)

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.

Authenticate with squirrelscan using device authorization flow.

Usage

squirrel auth login [options]

Options

Option	Alias	Description	Default
`--device-name`	`-d`	Name for this device	hostname

Example

squirrel auth login

Opens browser for authentication. After completing login:

✓ Authenticated as [email protected]
  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, and 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), the organization it acts for, and, for API keys, the granted scopes.

The org line is the one to read before spending anything. Cloud audits are charged to your active org, which the dashboard org switcher sets. If you belong to more than one org, status names which one is active and how many you have, and squirrel keys create refuses to guess.

Usage

squirrel auth status [options]

Options

Option	Description
`--json`	Output as JSON

Example

Logged-in session:

squirrel auth status

Authenticated as [email protected]
  Source: logged-in session
  Org: acme (Acme Inc)
  Org id: org_2xK9vQ
  Active org of 2. Cloud runs spend this org's credits; switch orgs in the dashboard.
  Device: macbook-pro
  Expires: Feb 2, 2027
  Credits: 950

Org shows the slug (also what your dashboard URL uses); Org id shows the id that appears on credit ledger rows. The count line appears only when you belong to more than one org. Resolving the org needs the API, so the org lines are omitted when it can’t be reached: status still reports your identity.

The active org is server state, set by the org switcher in the dashboard. There is no CLI flag that retargets an audit’s spend: --org selects an org for squirrel keys only. To bill a run to a different org, switch orgs in the dashboard, or use an API key minted for that org.

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

Authenticated as [email protected]
  Source: SQUIRRELSCAN_API_KEY env var
  Org: Acme Inc
  Org id: org_2xK9vQ
  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": "[email protected]", "name": "CI Bot" },
  "token": { "deviceName": null, "expiresAt": null },
  "apiKey": {
    "name": "CI – production",
    "scopes": ["audits:write", "credits:read"],
    "keyEnv": "production"
  },
  "org": { "id": "org_123", "slug": null, "name": "Acme Inc" }
}

For a login session the same call reports the active org and the org count:

{
  "authenticated": true,
  "source": "login",
  "user": { "id": "u_123", "email": "[email protected]", "name": "You" },
  "token": { "deviceName": "macbook-pro", "expiresAt": "2027-02-02T00:00:00.000Z" },
  "org": { "id": "org_2xK9vQ", "slug": "acme", "name": "Acme Inc" },
  "orgCount": 2
}

whoami

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

squirrel auth whoami

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

Edit this page

Subcommands

API token (CI / headless)

Minting a key from the CLI

Credential precedence

Environment-aware prefixes

Scopes

GitHub Actions

login

Usage

Options

Example

Troubleshooting

logout

Usage

Example

status

Usage

Options

Example

whoami

Related