CLI

The LatentKit CLI is the terminal companion for the console and SDKs.

Use it when you want to:

• sign in from a terminal without copying a raw API key
• test chat, embeddings, images, speech, transcription, and video from your shell
• check which workspace, app, and credits your account is using
• inspect logs, traces, usage, providers, routes, and connections
• create, rotate, or revoke API keys from an approved account session
• run CI checks with stable exit codes and JSON output

The npm package is @latentkit/cli. The binary name is latentkit.

Install

You need Node.js 18 or newer.

npm install -g @latentkit/cli
latentkit --help

If you do not want a global install, use:

npx @latentkit/cli --help

First login

Run:

latentkit login

The CLI prints a browser URL and a short confirmation code.

1. Open the URL.
2. Sign in to your LatentKit account.
3. Confirm the code shown in your terminal.
4. Return to the terminal.

After approval, the CLI stores a local profile in your operating-system config directory:

The file stores a LatentKit account access token, not your raw runtime API key. The CLI uses that account token for control-plane commands such as logs, routes, keys, and usage.

Treat this profile as a secret. Do not commit, upload, share, or paste it into support messages or AI prompts. Use latentkit logout to remove a profile you no longer need.

Confirm your account

latentkit whoami

Typical output:

Account : user_...
Tenant  : Example Workspace (t_...)
App     : Default Router
Auth    : ide_access_token
Credits : $99.70

If Account is (unknown), update the CLI, log out, and sign in again. If it continues, contact support with the CLI version and workspace name—never the profile file or token.

Send a test request

For a quick runtime check:

latentkit chat "Say hello from LatentKit."

For machine-readable output:

latentkit chat "Say hello from LatentKit." --json

Common runtime commands:

latentkit chat "Summarize the CAP theorem"
latentkit embed "text to embed"
latentkit image "a red bicycle" --size 1024x1024
latentkit speech "hello there" --voice alloy
latentkit transcribe ./meeting.mp3 --language en
latentkit video "a short product scene" --duration 4

Your assigned route still controls provider/model selection. Do not pass provider or model selection to the runtime commands unless the command explicitly documents that option.

Choose a workspace app

List apps your account can use:

latentkit apps

Set the default app for the active profile:

latentkit apps use app_123

You can also pass an app for a single command:

latentkit chat "Route this" --app app_123

Profiles

Profiles let you keep separate local logins for different workspaces, environments, or users.

latentkit profiles
latentkit login --profile production
latentkit profiles use production
latentkit whoami --profile production
latentkit logout --profile production

For temporary config in tests or automation:

export LATENTKIT_CONFIG_DIR="/tmp/latentkit-config"

Logs, traces, usage, and routes

Most observability and management commands need a workspace id. In CLI flags this is called --tenant.

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
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

Use logs tail while debugging a local app. It polls recent requests and deduplicates by request id.

Route publishing

Route changes are role-checked on the server. Use these commands only after you have inspected the route in the console or with routes inspect.

latentkit routes inspect pol_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

Runtime API keys can send AI requests and run checks. Publishing and rollback require an account login token from latentkit login.

API key management

These commands use your account login token and enforce your workspace role on the server.

latentkit keys --tenant t_123 --app-slug default
latentkit keys create --tenant t_123 --app-slug default --label ci
latentkit keys rotate key_1 --tenant t_123
latentkit keys revoke key_1 --tenant t_123

New raw API keys are shown once. Store them in a server-side secret manager immediately.

Provider connections

For managed Platform Access:

latentkit connections create --tenant t_123 --provider-def pd_openai --name "OpenAI" --type managed

For BYOK, pass the provider secret through stdin. Do not put provider secrets in shell history as flags.

printf '%s' "$OPENAI_KEY" | latentkit connections create \
  --tenant t_123 \
  --provider-def pd_openai \
  --name "OpenAI BYOK" \
  --type byok

Then test or delete:

latentkit connections test conn_1 --tenant t_123
latentkit connections delete conn_1 --tenant t_123

Config checks and CI

For CI, prefer a runtime API key in LATENTKIT_API_KEY. Browser login is for humans.

export LATENTKIT_API_KEY="lk_..."
latentkit ci check --json

Validate environment and connectivity:

latentkit doctor
latentkit env validate

Export and check config drift:

latentkit config export --tenant t_123 > latentkit.config.json
latentkit config validate latentkit.config.json
latentkit config diff latentkit.config.json --tenant t_123

config diff exits with code 6 when drift is detected, which makes it useful in CI.

There is no config import command. Connection secrets are never exported, and route contents should be changed through explicit route and connection commands.

Credential precedence

The CLI resolves credentials in this order:

1. --api-key <key>
2. LATENTKIT_API_KEY
3. the selected local profile from latentkit login

Base URL resolves in this order:

1. --base-url <url>
2. LATENTKIT_BASE_URL
3. the selected profile
4. https://ai.latentkit.com

Useful environment variables:

JSON output

Every command supports --json. Use it for scripts, AI agents, and CI:

latentkit whoami --json
latentkit routes --tenant t_123 --json
latentkit logs --tenant t_123 --days 1 --json

Human output is optimized for terminals. JSON output is the stable contract for automation.

Exit codes

For AI agents and automation

When an AI agent uses the CLI:

• prefer --json
• do not print raw API keys or provider secrets into prompts or logs
• use LATENTKIT_API_KEY for CI and non-interactive environments
• use latentkit login only when a human can approve the browser grant
• pass --tenant explicitly for logs, traces, routes, usage, costs, providers, and connections
• store temporary profiles under LATENTKIT_CONFIG_DIR when running tests
• capture request_id from errors and traces for debugging

Common problems

Not authenticated

Run one of:

latentkit login

or:

export LATENTKIT_API_KEY="lk_..."

Missing --tenant <workspace-id>

Observability and management commands need a workspace id:

latentkit usage --tenant t_123

Runtime request fails but login works

Check:

1. latentkit whoami
2. latentkit apps
3. latentkit routes --tenant t_123
4. the console route and provider health

The account login can be valid while the selected app or route still lacks an eligible published route for that request.

Related pages

• Quickstart
• Authentication
• JavaScript SDK
• Python SDK
• Troubleshooting