Skip to main content

​
Sign In

Authenticate with Circuit.
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 engine 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:
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.
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 upload, 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.
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.
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.
  • 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.