CLI login

The CLI login endpoints let a terminal or a coding agent create a Strix account and get an API token without a dashboard visit. The flow uses OAuth 2.0 device authorization. The open-source CLI runs this flow with the strix cloud login command.

Start device authorization

This endpoint does not require authentication. The browser step establishes the user identity.

curl -X POST "https://app.strix.ai/api/v1/cli/login"

The response contains a user_code, a verification_uri_complete, a device_code, an expires_in value, and a poll interval in seconds. Show the user_code to the user and open verification_uri_complete in a browser. Keep the device_code private.

Poll for completion

Poll this endpoint with the device_code at the returned interval.

curl -X POST "https://app.strix.ai/api/v1/cli/login/poll" \
  -H "Content-Type: application/json" \
  -d '{"device_code": "<DEVICE_CODE>", "scope_profile": "recommended", "client_instance_id": "<STABLE_INSTALLATION_ID>", "device_name": "macOS CLI · a1b2c3d4"}'

Choose scope_profile as minimal, recommended, or full, or send a custom scopes array. The server always includes the minimum scopes scans:read, scans:write, and billing:read; the member’s role caps the final set. The CLI exposes --scope-profile and --scopes. The open-source CLI generates one opaque client_instance_id per installation and a privacy-safe device_name that contains no hostname. Sending both makes later sign-ins from the same installation replace that session’s secret and expiry in the same database row instead of creating an unlimited series of keys. Different installations remain separately visible and revocable in Settings → API Access as CLI sessions. Omit both fields only for compatibility with an older client. Without either field, the server uses Recommended: the three minimum scopes plus vulnerabilities:read, vulnerabilities:write, schedules:read, schedules:write, assets:read, assets:write, organizations:read, uploads:write, and billing:write. This lets an admin agent complete the user-approved Link/MPP credit top-up flow when a scan needs credits. Credential creation through tokens:write still requires Full or an explicit custom scope request. Workspace listing and switching the current CLI session do not themselves require organizations:read or tokens:write. Scopes that the member’s role cannot receive are omitted. While the user has not confirmed in the browser, the response is an error with the code authorization_pending. Continue to poll. If the response code is slow_down, increase the poll interval by 5 seconds.

Interactive workspace and scope selection

Send "interactive": true in the poll request to select a workspace and scopes after the browser step. When the user confirms in the browser, the response then contains selection_required: true, a short-lived selection_token, the workspaces of the user, and the full scope catalog with descriptions. Each scope entry shows if the scope is part of the minimum set, if it is a default, and the lowest member role that can receive it. Complete the login with the selection:

curl -X POST "https://app.strix.ai/api/v1/cli/login/complete" \
  -H "Content-Type: application/json" \
  -d '{"selection_token": "<SELECTION_TOKEN>", "organization_id": "<uuid>", "scope_profile": "minimal"}'

The workspace must be one of the memberships of the user. The server always includes the minimum scopes. The role of the member limits the final set. The selection token expires after 10 minutes. The strix cloud login command uses this flow in an interactive terminal. It offers a workspace picker and the scope presets Recommended, Full access, and Minimal. The --workspace flag selects a workspace by name or ID without a prompt. When the user confirms, the response contains the account and a personal API token:

{
  "api_token": "strix_...",
  "organization_id": "<uuid>",
  "organization_name": "My workspace",
  "email": "user@example.com",
  "expires_at": "2026-11-24T00:00:00.000Z",
  "is_new_user": true,
  "scopes": ["scans:read", "scans:write", "billing:read"],
  "scope_ceiling": ["scans:read", "scans:write", "billing:read"],
  "requested_scopes": ["scans:read", "scans:write", "billing:read"],
  "scope_profile": "minimal",
  "token_id": "<uuid>",
  "credential_source": "cli",
  "device_name": "macOS CLI · a1b2c3d4"
}

The api_token value is shown only once. Store it in a secure location. scope_ceiling is the immutable maximum authority accepted at this login; workspace and profile changes can narrow it but cannot widen it. Broader access requires another browser sign-in. For a first-time user, Strix creates the account and a default workspace automatically. The token is valid for 90 days.

CLI output and automation

In a terminal, strix cloud output is compact and action-oriented: lists favor names, branches, lifecycle states, and numbered selectors. Internal organization and user IDs are omitted, while a required selector that is too long for a compact table is repeated losslessly in a copyable block. Paginated lists print the next --page or --offset, and detail views prioritize useful prose within a safe terminal bound. A bare resource group with a safe read operation runs its default list/read action; use -h or help to list that group’s verbs. Pass --json for the complete record. When stdout is redirected or is not a terminal, output automatically becomes JSON and the CLI never prompts. Binary downloads are the exception: redirect their raw bytes intentionally, or use --output FILE --json to write the file and receive structured download metadata.

Workspaces

A personal token belongs to one workspace. Use these endpoints to list the workspaces of the user, create a workspace, and retarget the active personal token to another workspace. All three need a personal token from the login flow. A service token belongs to a single workspace and cannot use them.

List workspaces

curl -X GET "https://app.strix.ai/api/v1/workspaces" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

Required scope: none. The bearer must be a personal token. Keeping this recovery operation scope-independent lets a Minimal CLI session discover and switch workspaces. Each entry contains id, name, role, and current. In an interactive terminal, the CLI presents the entries as a numbered list and hides the long IDs from the compact table. JSON output still contains the complete records:

strix cloud workspaces             # numbered human-readable list
strix cloud workspaces --json      # complete records for agents

Create a workspace

curl -X POST "https://app.strix.ai/api/v1/workspaces" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Team"}'

Required scope: organizations:write and an admin role. This scope is not part of the Recommended preset. The user becomes the admin of the new workspace.

Switch the active token to another workspace

curl -X POST "https://app.strix.ai/api/v1/workspaces/<ORGANIZATION_ID>/token" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "X-Strix-Workspace: <CURRENT_ORGANIZATION_ID>" \
  -H "Content-Type: application/json" \
  -d '{"scope_profile": "minimal"}'

Required scope: none. The bearer must be a personal token. The user must be a member of the workspace. An ordinary switch preserves the server-side requested profile, then the target-workspace role caps its effective scopes. A scope_profile or custom scopes request may narrow within scope_ceiling; a request beyond the ceiling returns 403 and requires login again. The endpoint retargets the same row and keeps its bearer secret and expiry, making an exact retry safe after a lost response.

strix cloud workspaces use 3              # number from the current list
strix cloud workspace use "My Team"       # singular alias and exact name
strix cloud workspaces use <WORKSPACE_ID> # stable ID for automation
strix cloud session scopes               # effective scopes and login ceiling
strix cloud session scopes set minimal   # narrow without logging in again

workspace and workspaces are aliases. The use selector accepts a displayed number, exact case-insensitive name, or workspace ID. If names are duplicated, use the displayed number or ID. A list number is convenient for a person but is not a stable automation identifier; an agent should use the ID from --json. Ordinary switching does not ask for scopes again. workspaces use --json returns the resulting profile, granted/requested/ceiling scopes, expiry, CLI-session metadata, and a stored boolean without returning the bearer secret. The CLI updates local metadata only after success and never persists --token or STRIX_API_TOKEN overrides.

Session safety and revocation

Managed CLI-session requests include X-Strix-Workspace with the organization selected when the process started. If another shell switches the same device session, a stale command receives 409 workspace_session_changed instead of silently running against the new workspace. JSON CLI output preserves the error code plus current and expected workspace IDs for agent recovery. GET /workspaces, GET /cli/session, and an exact workspace-switch retry remain available for recovery; stale processes cannot change scopes or revoke the session. Direct API clients using a CLI session should send the same header; ordinary API tokens are unchanged.

strix cloud session                        # fetch remote session state
strix cloud session scopes --json          # effective/requested/ceiling scopes
strix cloud session scopes set recommended
strix cloud logout                         # remote revoke, then local deletion
strix cloud logout --local-only            # deliberate emergency local cleanup

GET /api/v1/cli/session returns the current session. PATCH changes scope_profile or custom scopes within the ceiling. DELETE revokes that same bearer without requiring tokens:write. Normal logout keeps the local token after transport or server failures so revocation can be retried; a definitive success or already-invalid (401) response permits local deletion. Revoked and expired CLI-session rows are retained for a bounded audit window, then purged.

Tab completion

Completion is generated by the source CLI as well as packaged binaries. It therefore works with uv run strix too:

source <(strix completions zsh)
# From a source checkout:
source <(uv run strix completions zsh)
# bash: source <(strix completions bash)
# fish: strix completions fish | source

Add the appropriate command to the shell startup file to enable it in future terminals. Completion covers cloud groups, verbs, flags, and singular resource aliases; it does not send a request or expose token values.

Getting Started

Guides

Start device authorization

Poll for completion

Interactive workspace and scope selection

CLI output and automation

Workspaces

List workspaces

Create a workspace

Switch the active token to another workspace

Session safety and revocation

Tab completion

​Start device authorization

​Poll for completion

​Interactive workspace and scope selection

​CLI output and automation

​Workspaces

​List workspaces

​Create a workspace

​Switch the active token to another workspace

​Session safety and revocation

​Tab completion

Start device authorization

Poll for completion

Interactive workspace and scope selection

CLI output and automation

Workspaces

List workspaces

Create a workspace

Switch the active token to another workspace

Session safety and revocation

Tab completion