CLI setup and authentication

Use the native credential store for an interactive workstation and an environment API key for CI or another headless environment. Both authenticate the CLI to one resolved API origin.

Before you begin

Install the CLI and review API key security. Native login supports macOS Keychain, Windows Credential Manager, and glibc Linux with libsecret plus an unlocked desktop D-Bus Secret Service. Musl Linux and headless native stores are unsupported.

Run ba --login in an interactive terminal. Enter an existing Tenant API key at the invisible bootstrap prompt; the CLI validates it, creates a dedicated key named for the CLI and hostname, stores that key under the resolved API origin, and discards the bootstrap key.

Logging in again creates and verifies a replacement before revoking the previous dedicated key. A failure before local replacement leaves the previous credential untouched. If writing or verifying the replacement fails, the CLI attempts to restore and verify the previous entry and revoke the new remote key.

Previous-credential preservation is guaranteed only when rollback verification succeeds. If rollback fails, local credential state is unverified; remove the reported native service/account entry manually and revoke the reported new key before retrying. If only remote cleanup fails after a successful rollback, the previous credential remains available and the CLI reports the new key ID to revoke.

Verify authentication

ba --status reports the API origin, configuration source (flag, environment, yaml, or default), credential source (environment, native credential store, or none), stored key ID when available, and remote validity (valid, invalid, invalid (expired), or not checked). It validates the selected credential remotely and never prints its token.

Sign out

ba --logout targets the origin-scoped native credential even when an environment override is active. It revokes the remote dedicated key before deleting the local entry, preserving the local entry if remote revocation fails so you can retry.

A revoked, expired, or absent remote key allows local cleanup with a warning. If local deletion fails after remote revocation, the CLI reports the native service and account identifiers for manual removal. It also warns when BLAZING_AGENTS_API_KEY remains active.

ba --login
ba --status
ba --logout

Status should show the origin, sources, key ID when stored, and validity without showing the API key token.

Authenticate in CI

Set BLAZING_AGENTS_API_KEY from the CI system's secret manager. It takes precedence over the native store, is not persisted, and must not appear in command lines, logs, YAML, or repository files. When CI is set and the variable is missing or empty, the CLI fails before loading the native store or prompting.

See Scripting and CI for a complete job.

Troubleshoot the credential store

No plaintext credential fallback

If the native store is unavailable or an entry is invalid, the CLI fails. It never writes a credential to plaintext configuration or falls back to another store.

Unlock the desktop session and verify the platform service before retrying:

security show-keychain-info "$HOME/Library/Keychains/login.keychain-db"
security unlock-keychain "$HOME/Library/Keychains/login.keychain-db"

On Linux, install libsecret and use an unlocked Secret Service collection in a desktop D-Bus session. For a corrupt or partially removed entry on any OS, revoke the dedicated key through the platform, remove the native entry using the service/account identifiers printed by the CLI, then sign in again.