CLI Reference

Use the kt CLI to own the declarative-config lifecycle from the terminal. Its primary job is to help you author, validate, run, distribute, and inspect the same policy-config.yaml that governs runtime behavior.

Use this page when

• You need to find the right CLI command group for a task (policy validation, gateway runtime, IAM, events, spend, etc.).
• You are starting with the Keeptrusts CLI and need the installation, configuration, and typical workflow overview.
• You want to understand global flags, environment variables, and config precedence before diving into individual commands.

If you are new to this operating model, start with Config-First Workflow before diving into individual commands.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Use this section when

• Bootstrap a usable config and validate it before rollout.
• Run or administer the gateway from a delivery pipeline or operator shell.
• Retrieve events, escalations, exports, and history without manual UI steps.
• Turn config rollout, IAM, spend, and control workflows into code-driven operations.

Installation

See Installation for platform-specific instructions.

Start here

If you need to...	Start with	Then
Understand the recommended product workflow	Config-First Workflow	Quickstart
Bootstrap a config and verify your environment	kt init	kt doctor
Validate a policy before rollout	kt policy lint	kt policy test
Run the gateway locally or in managed mode	kt gateway run	Managed Mode
Investigate runtime outcomes from the terminal	kt events	kt escalations and kt export-jobs
Manage surrounding control-plane inventory as code	kt control	kt webhook and IAM command groups

Follow this order

1. Read Config-First Workflow so your team treats policy-config.yaml as the product surface.
2. Install the CLI and confirm connectivity with kt doctor.
3. Generate or inspect a config with kt init and kt config show.
4. Validate and test policy before traffic reaches production.
5. Run the gateway from that config, then keep investigation and rollout in the same CLI or console loop.

Full Coverage

Use CLI Command Groups for the complete public command surface, including gateway lifecycle commands, knowledge-base and history workflows, IAM and agent administration, secrets and config variables, webhooks, control manifests, budgets, provider budgets, and gateway keys.

Command Groups

Workflow	Commands	Guide
Bootstrap and diagnostics	kt init, kt config show, kt doctor	CLI Command Groups
Auth and tokens	kt auth login, kt auth logout, kt auth whoami, kt auth token ...	CLI Command Groups
Policy authoring and rollout	kt policy lint, kt policy test, kt policy push, kt policy deploy	CLI Command Groups
Gateway runtime and lifecycle	kt gateway ..., kt run --managed	CLI Command Groups
Events, export jobs, escalations	kt events ..., kt export-jobs ..., kt escalation ...	CLI Command Groups
State, secrets, config vars, knowledge-base, control, webhooks	kt history ..., kt secret ..., kt config-var ..., kt knowledge-base ..., kt kb ..., kt control ..., kt webhook ...	CLI Command Groups
IAM, teams, roles, agents	kt user ..., kt team ..., kt role ..., kt iam policy ..., kt agent ...	CLI Command Groups
Spend governance and access keys	kt spend summary, kt spend budget ..., kt spend provider-budget ..., kt spend gateway-key ...	CLI Command Groups

Focused Guides

Topic	Guide
Authentication	kt auth
Local diagnostics	kt doctor
Local gateway runtime	kt gateway run
Gateway administration	kt gateway admin
Managed polling mode	Managed Mode
Config inspection	kt config show
Policy validation	kt policy lint
Policy test runner	kt policy test
Event retrieval	kt events
Escalation management	kt escalations
Export jobs	kt export-jobs
Knowledge Base management	kt knowledge-base
History management	kt history
Secret management	kt secret
Config variables	kt config-var
Control manifests	kt control
Webhook management	kt webhook
Agent management	kt agent
User management	kt user
Team management	kt team
Role management	kt role
IAM policies	kt iam policy
Spend and budgets	kt spend
Streaming compatibility	Streaming & SSE
WebSocket compatibility	WebSocket Gateway
Format translation	Format Translation
Ordered failover and routing	Multi-Provider Fallback

Global Options

Flag	Env Var	Description
--json	—	Output in JSON format
--api-url	KEEPTRUSTS_API_URL	Keeptrusts API URL
--api-token	KEEPTRUSTS_API_TOKEN	Scoped API token for authenticated API access
--verbose	RUST_LOG	Enable verbose logging

Configuration Precedence

Settings are resolved in this order (first wins):

1. CLI flags — kt gateway run --listen 0.0.0.0:9090
2. Environment variables — provider credentials such as OPENAI_API_KEY, direct CLI auth via KEEPTRUSTS_API_TOKEN, and gateway runtime auth via KEEPTRUSTS_GATEWAY_TOKEN
3. Config file — targets, routing, policies, and limits in policy-config.yaml
4. Defaults — built-in sensible defaults

Environment Variables

Variable	Description	Example
KEEPTRUSTS_API_URL	API base URL	https://api.keeptrusts.com
KEEPTRUSTS_API_TOKEN	Scoped API token for direct CLI or API auth	kt_live_...
KEEPTRUSTS_GATEWAY_TOKEN	Unified gateway runtime/control-plane token	kt_gw_...
OPENAI_API_KEY	Provider credential consumed via secret_key_ref in policy-config.yaml	sk-...
ANTHROPIC_API_KEY	Provider credential consumed via secret_key_ref in policy-config.yaml	sk-ant-...
KEEPTRUSTS_GATEWAY_ID	Gateway identifier for managed mode	proxy_main
KEEPTRUSTS_CONFIG	Path to config file	./policy-config.yaml
KEEPTRUSTS_OTLP_ENDPOINT	OTLP collector endpoint	http://localhost:4318

Emergency upstream overrides still exist for break-glass debugging, but the standard CLI workflow keeps provider targets in policy-config.yaml and provider secrets in secret_key_ref.env or secret_key_ref.store.

Typical Workflow

# 1. Initialize a new project
kt init

# 2. Edit the generated config
vim policy-config.yaml

# 3. Add provider credentials outside the YAML
export OPENAI_API_KEY="sk-your-openai-key"

# 4. Validate the config
kt policy lint --file policy-config.yaml

# 5. Run tests
kt policy test --json

# 6. Optionally enable event reporting into the control plane
export KEEPTRUSTS_API_URL="https://api.keeptrusts.com"
export KEEPTRUSTS_GATEWAY_TOKEN="kt_gw_your_gateway_token"

# 7. Start the gateway from the declarative config
kt gateway run \
  --listen 0.0.0.0:41002 \
  --policy-config policy-config.yaml

# 8. Send a test request through the gateway
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello, world!"}]
  }'

# 9. Check events
kt events tail --since 5m --json

Use KEEPTRUSTS_API_TOKEN for direct CLI or API auth, and KEEPTRUSTS_GATEWAY_TOKEN when a hosted or managed gateway authenticates to the control plane.

For AI systems

• Canonical terms: Keeptrusts CLI, kt, policy-config.yaml, gateway, declarative config.
• Top-level command groups: kt init, kt doctor, kt auth, kt policy, kt gateway, kt events, kt escalation, kt export-jobs, kt knowledge-base, kt history, kt secret, kt config-var, kt control, kt webhook, kt agent, kt user, kt team, kt role, kt iam, kt spend.
• Global flags: --json, --api-url, --api-token, --verbose.
• Environment variables: KEEPTRUSTS_API_URL, KEEPTRUSTS_API_TOKEN, KEEPTRUSTS_GATEWAY_TOKEN, KEEPTRUSTS_GATEWAY_ID, KEEPTRUSTS_CONFIG, KEEPTRUSTS_OTLP_ENDPOINT.
• Configuration precedence: CLI flags > environment variables > config file > defaults.
• Entry point for new users: Config-First Workflow then Quickstart.

For engineers

• Prerequisites: Rust 1.91.1+ for building from source, or download the prebuilt binary from Installation. Connectivity to the Keeptrusts API requires a scoped token.
• Validate your setup: kt doctor checks connectivity, auth, and config file validity in one command.
• Typical CI integration: kt policy lint --file policy-config.yaml && kt policy test --json as a pre-merge gate.
• Use KEEPTRUSTS_API_TOKEN for direct CLI auth. Use KEEPTRUSTS_GATEWAY_TOKEN when running a hosted or managed gateway against the control plane.

For leaders

• The CLI enables a GitOps-friendly, config-as-code approach to AI governance — policies are reviewed, versioned, and deployed like application code.
• Automation via kt policy lint and kt policy test in CI pipelines prevents misconfigured policies from reaching production.
• All control-plane operations (IAM, spend, events, escalations) are available from the CLI, enabling auditable infrastructure-as-code workflows without manual UI steps.
• Teams can split responsibilities: engineers own policy-config.yaml, leaders approve rollouts via the console.

Next steps

• Installation — Platform-specific install instructions
• Config-First Workflow — Recommended workflow for teams
• Quickstart — End-to-end first run
• CLI Command Groups — Complete public command surface