Skip to main content
Every CLI command that calls the API needs a credential. Humans sign in once with unkey login. CI and other machines pass a root key with a flag or an environment variable.

Sign in with unkey login

The command writes a confirmation code and a URL to stderr. In a terminal, it asks whether to open the URL, and defaults to leaving the browser closed. Open the URL yourself or select Open browser. Sign in, check that the code matches the terminal, and choose what the CLI can do. Authorizing the login finishes it. The CLI stores one session per workspace in the system keychain and prints Signed in. to stdout without printing the tokens. When the keychain is unavailable, it writes ~/.unkey/sessions.json (mode 0600) instead and prints a warning to stderr. See unkey login. unkey auth login does the same thing. You can approve the login with any permission your role includes. The session receives only the permissions you select. See Root key permissions. The file fallback holds session tokens in plain text, so treat that file like a credential. Keep it out of version control and off shared machines. To store a key you already have, without a browser, run this and paste the key at the hidden prompt:
That flag does not check the key with the API. A wrong key only shows up on your next resource command.

Override the stored key

For one command, pass --root-key:
For a whole shell session, set UNKEY_ROOT_KEY:

Which key resource commands use

Resource commands, including the legacy unkey api paths, use the first credential they find:
  1. The --root-key flag.
  2. The UNKEY_ROOT_KEY environment variable.
  3. An explicit --config file. That file wins over a stored CLI session. UNKEY_CONFIG and the default path do not.
  4. The CLI session from unkey login, when it belongs to the API this command is calling.
  5. A root key from unkey login --root-key. A key still in ~/.unkey/config.toml is used before the keychain, because that file only exists when the last save could not reach the keychain. A different --config or UNKEY_CONFIG path is read as a file and is not copied into the keychain.
unkey deploy has no --config flag. It uses --root-key, then UNKEY_ROOT_KEY, then the CLI session, then the saved root key. If there’s no credential anywhere, the command stops before calling the API with no credentials provided. If the API rejects the credential, you get Authentication failed: ... and a hint to run unkey login. In CI, set UNKEY_ROOT_KEY as a secret. See unkey deploy.

Check which credential the CLI uses

unkey whoami is the same as unkey auth status. It picks a credential in the same order as resource commands and accepts the same --root-key, --config, and --api-url overrides. It never prints the credential.
  • Browser session: The CLI checks the session with the API and shows its workspace, session ID, and user ID. Authentication is verified. An expired access token is refreshed first, as for any other command.
  • Root key: Authentication is unchecked, and no workspace is shown. The API has no endpoint that confirms a root key or reports its workspace without a resource permission. Run a resource command to test the key.
  • No credential: Authentication is missing.
If the check fails, Authentication is failed, Detail gives the reason, and the command exits with a nonzero status. A missing credential also exits with a nonzero status. Use --json or --output=json for scripts. This command reports on the CLI login. To inspect an API key, use unkey keys whoami.

Point at a different API host

--api-url (or UNKEY_API_BASE_URL) sets the base URL for resource commands and for unkey login. unkey deploy has --api-base-url. The default is https://api.unkey.com. unkey login stores that URL with the session. Later commands send the session to the same URL. If you pass --api-url or --api-base-url for a different host, the CLI skips the session and uses a root key instead. You don’t normally need to change the URL.

Sign out

unkey logout revokes the active CLI session and removes it from this machine. Its success message goes to stdout without a workspace ID. If another stored workspace becomes active, the CLI reports that on stderr. Workspace IDs still identify sessions when you use unkey workspace switch. If server revocation fails, the CLI reports the failure on stderr and exits with a nonzero status instead of claiming success. Removing the local session alone does not prove that the server session has been revoked.
Last modified on November 4, 2026