Authentication
The CLI signs in through your browser, a device code or an API key, and in scripts and CI it reads the credential from a flag or an environment variable. Run polylane auth login to pick a method interactively, or pass a flag to skip the picker.
Sign-in methods
| Method | Command | Description |
|---|---|---|
| Browser | polylane auth login | For interactive use. The CLI opens your browser, receives the tokens on a localhost callback and refreshes them as they expire. |
| Device code | polylane auth login --no-browser | For SSH and headless machines. The CLI prints a URL and a code; open the URL on any device, enter the code, and the CLI polls until you approve. |
| API key | polylane auth login --api-key sk_xxxxx | For scripts, CI and agents. The CLI validates the key and stores it with a default workspace. |
After sign-in the CLI shows who you are and, if you belong to more than one workspace, asks you to pick a default, saved as workspace_id in ~/.polylane/config.json. Force a token refresh with polylane auth refresh.
API keys
Create a key under Settings > API Keys with Create an API key: name it, choose its scopes and copy it, because it is shown once. Keys start with sk_. In CI, set POLYLANE_API_KEY in the environment instead of running the login step, or pass the global --api-key <key> flag on a single call.
Credential precedence
When several credentials are present, the CLI resolves them in this order:
- The
--api-keyflag on the current command - The
POLYLANE_API_KEYenvironment variable - OAuth credentials in
~/.polylane/credentials.json api_keyin~/.polylane/config.json
An exported POLYLANE_API_KEY always beats a stale ~/.polylane/credentials.json, so a CI runner with the variable set does not pick up leftover OAuth tokens. polylane auth status shows which source is in use.
Check and switch
polylane auth status
polylane auth whoami
polylane auth logout
auth status shows the method in use, a masked token, the user and the workspace; auth whoami shows the current user. auth logout revokes OAuth tokens and clears stored credentials after a confirmation, which --yes skips; to switch accounts, log out and log in with the other credential.
Environment variables
| Variable | Description |
|---|---|
POLYLANE_API_KEY | API key for non-interactive auth |
POLYLANE_WORKSPACE_ID | Default workspace (ws_ id) |
POLYLANE_API_DOMAIN | API hostname override |
Use these in CI jobs and containers where you do not want to write to ~/.polylane/. Configuration lists the full set.
Related
- Configuration: the full precedence order, every environment variable and the files on disk.
- Scripting: JSON output, exit codes and the flags for CI and agents.
- API keys and OAuth: scopes, key management and OAuth clients.