unkey login starts a device login. You confirm the code in the dashboard, narrow the permissions if you want, and the CLI stores a session. Humans use unkey login. CI uses a root key.
unkey auth login runs the same command.
Usage
unkey logout revokes the session. unkey workspace switch changes the active workspace.
A denied or expired login stops with the reason. Run unkey login again to start over.
The CLI retries network errors and server errors while it waits. If the CLI receives a session but cannot store it, it revokes that session on the server and exits with an error. Run unkey login again once the keychain or ~/.unkey is writable.
Starting and polling logins is rate limited per IP address. When you hit the limit, the API answers ip_rate_limited.
Flags
string
API origin to call. Falls back to
UNKEY_API_BASE_URL. Defaults to https://api.unkey.com.boolean
Print the verification URL and do not open a browser.
string
Store a root key and skip the browser. Pass
- to read the key from stdin, with a hidden prompt when stdin is a terminal, so the key stays out of your shell history and process list. The command does not check the key with the API, and it does not read UNKEY_ROOT_KEY.Where the key is stored
The root key goes in the operating system secret store:- macOS Keychain, as a generic password with service
unkeyand accountroot_key - Windows Credential Manager, as a generic credential named
unkey/root_key - Linux Secret Service, through
secret-tool, with attributesservice=unkeyandaccount=root_key
security tool on stdin, so it does not appear in the process list, and reads it back to confirm the save.
If that store is unavailable (no secret-tool binary, or no Secret Service session on Linux), the CLI writes ~/.unkey/config.toml instead and prints that path. Only your user can read the file (mode 0600, in a 0700 directory):
~/.unkey/config.toml
~/.unkey/config.toml is copied into the secret store the next time the CLI reads or writes the default config, and the file is removed. That key replaces any older key in the secret store, because the file only holds a key when the last save could not reach the secret store. --config or UNKEY_CONFIG pointing at a different file is read as a file and is not copied into the keychain.
unkey login --root-key uses this same storage. Running the command again replaces the stored key.
The session has exactly the permissions you selected. It does not inherit every permission your user has. Any role can approve a login, limited to the permissions that role can grant.
unkey api and unkey deploy use a stored CLI session when neither --root-key nor UNKEY_ROOT_KEY is set, and the session’s API URL matches the command. An explicit --config on unkey api is used instead of the session. A root key saved with --root-key is the next fallback. See CLI authentication.