Skip to main content

​
Sign In

Authenticate with Circuit. 
circuit auth login
Opens a browser to authenticate. If you don’t have an account, one will be created. How it works:
  1. The CLI generates a unique auth handoff ID via the Circuit API.
  2. Opens your browser to the Circuit login page with the handoff ID.
  3. In the browser, your passkey signs a CLI-scoped permit (and a one-time KMS pktoken is stored on the api side, keyed to that permit, so hosted-execution signing works without an extra token).
  4. The CLI polls the API for the permit until the browser deposits it, then stores it in ~/.circuit/auth.toml under the [<env>] section matching CIRCUIT_ENV.
The login flow has a 300-second timeout. If authentication is not completed in time, the CLI exits. Stored credentials: 
[production]
permit = "circuit_permit_<payload_b64u>.<proof_b64u>"

[staging]
permit = "..."
The permit is a passkey-signed permit. The CLI treats it as an opaque bearer string and sends it as Authorization: Bearer <permit>. There is no separate wallet-execution authority token — the api resolves signing material server-side from the permit’s wallet.sign capability.

​
Local Sign-In (offline)

Authorize local signing — circuit run / circuit unwind against wallets in your local keystore — without a browser, a Circuit account, or any network. 
circuit auth login --local
This mints a local session permit signed by your local identity (a key the CLI generates on first circuit wallet add, stored under ~/.circuit/local/) and writes it to ~/.circuit/local/permit. When you need it:
  • Local circuit run / circuit unwind require a local session — they verify this permit and refuse if it’s missing or expired, pointing you back to circuit auth login --local.
  • circuit wallet * (add / list / delete / export) do not need it — they only use the local identity.
  • Hosted commands (circuit publish, circuit run --hosted …) use the browser sign-in above, not this.
Generate vs. use: minting the permit is an interactive step (you run this command); using it is not — once minted it’s cached, so unattended local runs sign without re-prompting until the permit expires, then you re-run circuit auth login --local.

​
Sign Out

Sign out from Circuit. 
circuit auth logout
Behavior:
  • Removes the [<env>] section from ~/.circuit/auth.toml (only the env matching CIRCUIT_ENV; other envs stay logged in). Deletes the file entirely if no envs remain.
  • No parameters required

​
Logged In User Info

Show current authenticated user. 
circuit auth whoami
Output (rendered as key: value lines; --json serializes the same fields):
  • username — who you’re signed in as.
  • environment — the active env (production / staging / local, from CIRCUIT_ENV or --env), and api — the endpoint it resolves to.
  • source — where the active credential came from: the auth.toml path (e.g. ~/.circuit/auth.toml), or CIRCUIT_TOKEN (env var) when set.
  • permit — the decoded permit payload (issuedAt, expiresAt, capabilities): the full grant itself, not a summary.
The raw token is never printed here — use circuit auth token.

​
Token

Print your bearer token for capture into CIRCUIT_TOKEN. 
circuit auth token            # the raw wire string
circuit auth token --json     # { "token": "circuit_permit_..." }
circuit auth token --decode   # the decoded pre-b64 permit (payload + proof)
  • Default prints nothing but the bare token, so TOKEN=$(circuit auth token) captures it directly. The only command that prints the credential — circuit auth whoami never does.
  • --json wraps the same value as { "token": "..." } for scripts that read structured output.
  • --decode prints the pre-b64 contents instead of the wire string: both base64url segments parsed — payload (issuedAt, expiresAt, capabilities) and the WebAuthn proof — raw, with no schema reshaping. A decode, not a verification (the CLI can’t check a passkey signature locally); it mirrors openssl x509 -text / step crypto jwt inspect. Combine with --json for one JSON document.
This is the bearer string the api authenticates. To read what it grants (capabilities + expiry) in plain language, use circuit auth whoami — the same way gh auth token prints the token and gh auth status shows what it’s good for.