Skip to main content

kapi auth

Authenticate the CLI against a deployed bowrain-server instance. This enables CLI commands to access workspace-scoped resources on a remote server.

Commands​

auth login​

Start an interactive login using the OAuth device flow:

kapi auth login --server https://app.bowrain.cloud

The CLI will display a URL and a one-time code. Open the URL in your browser, enter the code, and authorize the application. The CLI polls automatically and stores your token on success.

$ kapi auth login --server https://app.bowrain.cloud
Open https://app.bowrain.cloud/auth/device and enter code: ABCD-1234
Waiting for authorization...
Logged in as translator@example.com

The access token is stored in the OS keychain and used automatically by other CLI commands — see Token storage.

auth status​

Check the current authentication state:

kapi auth status

Output:

Server:  https://app.bowrain.cloud
User:    translator@example.com
Name:    Jane Translator
Expires: 2026-02-11 14:30:00

auth logout​

Remove the stored token:

kapi auth logout

How It Works​

The login flow uses the OAuth 2.0 Device Authorization Grant (RFC 8628), the same flow used by tools like gh auth login and gcloud auth login. This works in headless environments (SSH sessions, CI containers) where a browser redirect is not available.

  1. CLI requests a device code from the server
  2. User opens the verification URL in any browser and enters the code
  3. CLI polls the server until the user authorizes
  4. Server issues a JWT token, CLI stores it locally

Options​

FlagDescription
--serverServer URL to authenticate against (required for login)

Token Storage​

The access and refresh tokens live in the OS keychain, under the keys bowrain-auth:<server-url> and bowrain-refresh:<server-url>. Only non-secret metadata is written to auth.json in the bowrain config directory (~/.config/bowrain on Linux, ~/Library/Application Support/bowrain on macOS; BOWRAIN_CONFIG_DIR overrides it):

{
  "server_url": "https://app.bowrain.cloud",
  "expiry": "2026-02-11T14:30:00Z",
  "user": {
    "id": "usr_abc123",
    "email": "translator@example.com",
    "name": "Jane Translator"
  }
}

Server Authentication​

Authentication is required when connecting to a bowrain-server, which runs as a multi-user deployment with workspaces.