Skip to main content

​
Usage

In a terminal, choose browser sign-in or paste a personal access token. Browser sign-in is available on macOS and Linux. On Windows, use facet login --token or FACET_TOKEN. The registry verifies your identity before the CLI saves a usable credential. For CI and scripts, supply FACET_TOKEN instead of running interactive login.

​
Examples

​
Flags

​
boolean
Start browser sign-in and try to open the verification page. The URL and code are always printed, so you can finish manually if opening the browser fails.
​
boolean
Start the same sign-in flow without opening a browser. Open the printed URL on a device with a browser and enter the code while the command waits.
​
boolean
Paste a personal access token from your account at agentfacets.io. Requires an interactive terminal and cannot be combined with a browser flag.

​
Exit codes

​
Output

Browser sign-in prints a verification URL and user code, then Logged in as yourname. after verification succeeds. Press Ctrl+C to cancel. A pasted token also prints your account tier after it is verified.

​
Details

​
Browser verification

Confirm the code shown in your terminal on the verification page. Complete any registry account setup requested in the browser, then sign in again if the CLI asks you to finish onboarding. This uses the OAuth device authorization flow, with a public client ID and no embedded API key or client secret. The CLI does not need a browser redirect back to your machine. It accepts only the selected registry’s validated sign-in configuration and rejects unexpected authentication redirects.

​
Where the credential is stored

See browser credential storage and registry binding. A verified personal access token is written to the credentials file:

​
Token precedence

Commands select the first available credential in this order:
  1. Non-empty FACET_TOKEN.
  2. A saved personal access token.
  3. A browser session for the selected registry.
Login warns when a personal access token shadows your new browser session. Unset FACET_TOKEN and remove a saved token with facet logout before using browser sign-in. Removing a saved token can reveal an existing browser session. A rejected or unreadable selected credential fails the command. The CLI does not switch to another identity or retry anonymously after an authentication failure.

​
Session renewal

Commands renew browser sessions when needed and verify the registry identity before using them. A temporary network or registry verification outage fails the command while preserving local sign-in state; retry when connectivity returns. An expired or revoked session requires browser sign-in again. If a refresh outcome cannot be confirmed within the safe retry window, the CLI stops renewing it and asks you to sign in again rather than replaying an old refresh indefinitely.

​
Troubleshooting

Cause: verification expired, was denied, or was cancelled.Fix: start facet login --browser or facet login --no-browser again and complete the new verification prompt.
Cause: browser authentication succeeded, but registry onboarding is incomplete.Fix: open the onboarding page reported by the CLI, finish setup, then sign in again.
Cause: your browser credential storage failed its safety checks.Fix: check the local state requirements, correct ownership and permissions, then retry. The CLI will not weaken these checks to save credentials.
Cause: the personal access token file exists but is unreadable or malformed.Fix: check its permissions, run facet login --token to replace it, or set FACET_TOKEN for the current shell.
Cause: the registry refused the pasted token, usually because it was revoked, expired, or copied incompletely.Fix: mint a new token in your account settings and paste it again with facet login --token.

​
See also