Cloud Commands

The Khaos CLI provides commands for authenticating with Khaos Cloud, managing API tokens, and syncing evaluation results to the cloud dashboard.

khaos login

Authenticate with Khaos Cloud using an interactive device flow. Opens your browser for OAuth authentication and stores the token locally. If you're already logged in, it shows the current project and skips re-authentication.

Terminal
# Login (skips if already authenticated)
khaos login

# Force re-login (reset credentials)
khaos login --force

# Login with admin scope
khaos login --admin
FlagDescription
--force / -fForce re-login even if already authenticated
--adminRequest an admin-scoped token (requires project admin)
--scope <scope>Additional scopes to request (repeatable)

Authentication Flow

The login command uses OAuth 2.0 device authorization flow. Your browser opens to complete authentication, and the project is selected in the browser — no CLI flags needed.

Terminal
$ khaos login

→ Opening browser for authentication...
→ Waiting for authorization...
→ Successfully logged in to my-team/my-project

Credentials are stored in ~/.khaos/ via your cloud config. The API URL and dashboard URL are configured in the cloud config, not via CLI flags.

khaos logout

Clear stored credentials. Prompts for confirmation unless --force is used.

Terminal
# Logout (asks for confirmation)
khaos logout

# Logout without confirmation
khaos logout --force
FlagDescription
--force / -fSkip confirmation prompt

khaos sync

Upload pending evaluation runs to the Khaos Cloud dashboard. Automatically triggers login if not authenticated.

Terminal
# Sync all pending runs (auto-login if needed)
khaos sync

# Check sync status without uploading
khaos sync --status

# Sync a specific run by ID
khaos sync --run run-abc123

# Sync and clean up local artifacts after upload
khaos sync --cleanup

# Force sync including previously failed jobs
khaos sync --force
FlagDescription
--status / -sShow sync status (pending/failed jobs, login status)
--run / -r <id>Sync a specific run by identifier
--cleanup / -cDelete local artifacts after successful sync
--force / -fForce sync all pending jobs, even previously failed ones
--json / -jOutput results as JSON
CI/CD usage
In CI environments (GITHUB_ACTIONS or KHAOS_CI=1), interactive login is disabled. Set KHAOS_API_URL, KHAOS_API_TOKEN, and KHAOS_PROJECT_SLUG environment variables instead.

khaos tokens

Manage project-scoped API tokens for programmatic access and CI/CD integration. All token commands require admin scope.

Create a Token

Terminal
# Create a token with default name ("CI") and 90-day expiry
khaos tokens create

# Create with a custom name and scope
khaos tokens create --name "CI Pipeline" --scope ingest:write

# Create with custom expiry (days)
khaos tokens create --name "Short-lived" --expires-days 7

# Create and print CI env var lines
khaos tokens create --name "GitHub Actions" --print-env --show-token
FlagDescription
--name <name>Token name shown in the dashboard (default: "CI")
--project <owner/project>Target project (defaults to current cloud config project)
--scope <scope>Token scope (repeatable, default: ingest:write)
--expires-days <n>Expiry in days (default: 90, use 0 for no expiry)
--print-envPrint env var lines for CI secret setup
--show-tokenInclude full token value with --print-env

List Tokens

Terminal
# List all tokens for the current project
khaos tokens list

# List tokens for a specific project
khaos tokens list --project my-org/my-project

Rotate a Token

Revoke an existing token and mint a new one in a single operation. Useful for scheduled credential rotation in CI/CD.

Terminal
# Rotate by token ID
khaos tokens rotate <token-id>

# Rotate with a new name
khaos tokens rotate <token-id> --name "Rotated CI Token"

# Rotate and print new env vars
khaos tokens rotate <token-id> --print-env --show-token

Revoke a Token

Terminal
# Revoke by token ID
khaos tokens revoke <token-id>

Check Identity

Terminal
# Show current cloud identity (project + scopes)
khaos tokens whoami

# Output as JSON
khaos tokens whoami --json
Token security
Treat API tokens like passwords. Store them in environment variables or secret managers, never in source code or configuration files checked into version control.

Environment Variables

Cloud commands respect the following environment variables. These are especially useful in CI/CD pipelines where interactive login is not available.

VariableDescription
KHAOS_API_TOKENAPI token for authentication. When set, overrides any stored credentials from khaos login.
KHAOS_API_URLBase URL for the Khaos Cloud API. Set this for self-hosted deployments.
KHAOS_PROJECT_SLUGProject identifier for CI/CD. Required alongside KHAOS_API_TOKEN when not using interactive login.
KHAOS_CISet to 1 to signal CI mode (disables interactive prompts).
Terminal
# CI/CD usage example
export KHAOS_API_TOKEN="khaos_tok_abc123..."
export KHAOS_PROJECT_SLUG="my-org/my-project"

# Run evaluation and sync
khaos run my-agent --eval quickstart
khaos sync

Authentication Precedence

Khaos resolves authentication credentials in the following order:

  1. KHAOS_API_TOKEN environment variable (highest priority)
  2. Stored credentials from khaos login (cloud config)

If no credentials are found, commands that require authentication will prompt you to run khaos login (or fail in CI mode).

See Also