@latentkit/cli

Official command-line control surface for LatentKit. Device login, runtime testing, and control-plane inspection/management from your terminal or CI.

npm install -g @latentkit/cli
latentkit login
latentkit whoami

The binary is latentkit. Node 18+ required.

Authentication

Two credential types, resolved in this precedence (highest first):

1. --api-key <key> flag
2. LATENTKIT_API_KEY env var
3. the selected profile's stored login token or API key

• Humans: latentkit login runs a browser device flow. It prints a URL and a short confirmation code that you re-enter on the consent page (this binds the browser approval to your terminal). Tokens are stored in your OS config dir (~/.config/latentkit/config.json or %APPDATA%\latentkit) with 0600 permissions.
• CI: set LATENTKIT_API_KEY (a runtime lk_ key). Runtime keys can run chat/doctor/ci check; management commands (keys, routes publish, …) require an account login token.

Environment variables: LATENTKIT_API_KEY, LATENTKIT_BASE_URL, LATENTKIT_PROFILE, LATENTKIT_APP_ID, LATENTKIT_CONFIG_DIR, NO_COLOR.

Commands

Auth & context

| Command | Description | | --- | --- | | latentkit login | Device login (opens browser, confirm code) | | latentkit logout | Revoke the grant and clear the profile | | latentkit whoami | Show account / app / credits | | latentkit apps / apps use <id> | List apps / set default app | | latentkit profiles / profiles use <name> | List / switch credential profiles | | latentkit doctor | Validate credentials, connectivity, credits |

Runtime testing

latentkit chat "Summarize the CAP theorem" --route balanced
latentkit embed "text to embed"
latentkit image "a red bicycle" --size 1024x1024
latentkit speech "hello there" --voice alloy
latentkit transcribe ./clip.mp3 --language en
latentkit video "a drone shot over mountains" --duration 4

Observability (read-only, --tenant <workspace-id> required)

latentkit logs --tenant t_123 --provider openai --days 7
latentkit logs get req_abc --tenant t_123
latentkit logs tail --tenant t_123 --interval 3        # live poll, deduped by request_id
latentkit traces get req_abc --tenant t_123
latentkit usage --tenant t_123 --days 30
latentkit costs --tenant t_123
latentkit routes --tenant t_123
latentkit routes simulate pol_1 --tenant t_123 --endpoint chat
latentkit providers --tenant t_123
latentkit connections --tenant t_123
latentkit connections models conn_1 --tenant t_123

Management (mutating; workspace roles enforced server-side)

latentkit keys --tenant t_123 --app-slug default
latentkit keys create --tenant t_123 --app-slug default --label ci   # secret shown once
latentkit keys rotate key_1 --tenant t_123
latentkit keys revoke key_1 --tenant t_123

# Connections. BYOK secrets come from stdin — never a flag.
latentkit connections create --tenant t_123 --provider-def pd_openai --name "OpenAI" --type managed
echo -n "$OPENAI_KEY" | latentkit connections create --tenant t_123 --provider-def pd_openai --name "OpenAI BYOK" --type byok
latentkit connections test conn_1 --tenant t_123
latentkit connections delete conn_1 --tenant t_123

latentkit routes publish pol_1 --tenant t_123 --note "raise gpt weight"
latentkit routes rollback pol_1 ver_9 --tenant t_123

Config-as-code & CI

latentkit config export --tenant t_123 > latentkit.config.json
latentkit config validate latentkit.config.json
latentkit config diff latentkit.config.json --tenant t_123     # exit 6 on drift
latentkit ci check          # exit non-zero if unauthenticated / gateway down
latentkit env validate      # alias of doctor

config is read + drift detection (export/validate/diff). There is no config import: connection secrets are never exported, and route contents can't be safely recreated from the snapshot. Apply changes explicitly with routes publish and connections create.

Global flags

--json (stable machine output), --quiet, --no-color, --profile <name>, --app <id>, --base-url <url>, --api-key <key>.

Exit codes (stable)

| Code | Meaning | | --- | --- | | 0 | success | | 2 | validation (bad flags/args) | | 3 | auth (401 / not logged in) | | 4 | forbidden (403 / insufficient role) | | 5 | not found (404) | | 6 | config / local credential problem / config drift | | 7 | upstream (routing / provider / 5xx) | | 8 | rate limit (429) | | 9 | network (connection failure / timeout) | | 10 | version (426 unsupported / 410 disabled — run latentkit update) |

Telemetry

The CLI sends X-LK-Tool-Slug: latentkit-cli and X-LK-Tool-Version on every request. This powers version enforcement (so a disabled version can be blocked) and anonymous usage counts. No prompt content or arguments are sent as telemetry beyond the normal request you make.

JSON output contract

Every command supports --json. The JSON shapes and exit codes are considered part of the public interface and follow semver. Prefer --json in scripts.