Authentication

Authentication is optional. Gadriel Code scans entirely locally with no account and no token — authenticate only when you want the portal-connected extras.

You can install Gadriel, run gadriel code init, and scan, triage, and report without ever authenticating. Logging in links your CLI to your Gadriel account with a developer-portal token; that token is what unlocks the portal-facing features. This page covers what authentication is for, logging in, where the token lives, the token format, and offline operation.

Do you need to authenticate?

Works without a token	Requires a token
`gadriel code init`	`gadriel code policies update` (the private policy-repo fetch)
`gadriel code scan` — all modes, including `--offline`	Opt-in metrics sync (`--telemetry-enabled`)
`gadriel code findings`, `fix`, `report`, `sbom`	Portal management — seats, tokens, and licenses at `app.gadriel.ai/developers/`
`gadriel doctor`, `gadriel code mcp`

Local scanning is never blocked for lack of a token. The gate exists only on commands that talk to the Gadriel portal — see The token gate.

Log in

Get a token from the developer portal at https://app.gadriel.ai/developers/, then paste it into:

bash

gadriel auth login

You'll be prompted to paste the token. For non-interactive / scripted use, pass it directly:

bash

gadriel auth login --token "<tenant>_pf_live_xxxxxxxxxxxx"

Note

the legacy --email / --password flags have been removed — there is no password-grant flow. If you pass them, the CLI returns a clear error pointing you at the portal. Use a portal-minted token instead.

On success, the token is cached and validated. All future portal-connected commands run without re-authenticating — and your local commands behave exactly as before.

Where the token is cached

The token is written to:

~/.gadriel/auth/token.jwt   (file mode 0600 — owner read/write only)

The restrictive 0600 permission keeps the token readable only by your user account.

Token format

Tokens are opaque, tenant-prefixed strings of the form:

<tenant_slug>_pf_live_<random>

The tenant prefix is validated against your CLI's configured tenant. If you paste a token for the wrong tenant, Gadriel detects the mismatch before any portal work runs.
The token is server-validated — Gadriel does not decode secret claims locally.
The _pf_live_ infix is shell-safe for copy/paste.

The token gate

Commands that reach the Gadriel portal are token-gated. If the token is missing, invalid, expired, or for the wrong tenant, those commands fail with:

exit code 7

along with a message pointing you at gadriel auth login. Exit code 7 is the dedicated "auth" exit code in Gadriel's contract.

Local commands are exempt. gadriel code init, scan, findings, fix, report, and sbom never require a token — this is why authentication stays optional. The four gadriel auth subcommands (login, logout, status, refresh) are also exempt, so a user with an expired or grace-period token can always recover.

Check status

bash

gadriel auth status

  ✓ License token cached
  Tenant:        acme
  Email:         you@example.com
  Token name:    laptop
  Portal URL:    https://app.gadriel.ai/acme
  Scopes:        cli, code:scan
  Expires:       never (no expiry)
  Last validated: 2026-07-07 00:00 UTC (1 days ago)
  Status:        active

gadriel auth status reports token validity, expiry, and remaining offline-grace time. (gadriel status shows combined auth + sync status.)

Refresh

Force a fresh online validation and refresh the cached token:

bash

gadriel auth refresh

Use this after your portal admin changes your seat, scopes, or expiry.

Log out

Wipe the cached token (and best-effort revoke it server-side):

bash

gadriel auth logout

Offline mode

Gadriel is built to run without network access. For fully local-only operation — no outbound calls at all — set the offline environment variable:

bash

export PREFLIGHT_OFFLINE=1

In offline mode, Gadriel validates the cached token locally within its offline-grace window and skips every network step. This pairs naturally with air-gapped and CI setups; combine it with gadriel code scan --offline to also skip the OSV CVE sync (your coverage will report DEGRADED until you sync a snapshot — see Scan Coverage).

Next steps

Quickstart — scaffold a repo and run your first scan.
Configuration — set portal_url, offline_mode, and other keys in ~/.gadriel/config.toml.
Privacy — what does and does not leave your machine.