CLI Command Groups

This page catalogs the current public kt command surface. Use it when you need to find the right command family quickly, or when you are working through a platform-admin workflow that is broader than the task-focused guides in this section.

Use this page when

• You need to find the right kt command family quickly across the full CLI surface.
• You are working through a platform-admin workflow that spans multiple command groups.
• You want a single-page reference of all public commands with links to focused guides.

kt proxy still exists as a hidden deprecated alias for kt gateway, but new workflows should use kt gateway everywhere.

Primary audience

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

Bootstrap, Auth, And Diagnostics

Command	What it covers
kt init	Scaffold a starter policy-config.yaml and example tests for a new local project
kt config show	Print the effective CLI configuration after flag, env var, config-file, and default resolution
kt auth login	Sign in with email/password and store a reusable CLI session
kt auth logout	Remove stored session credentials for the active profile
kt auth whoami	Verify the active identity and API access context
kt auth token create	Mint a scoped API token for service, team, or user-bound automation
kt auth token list	List issued tokens and their active or revoked state
kt auth token revoke	Revoke a previously issued scoped token
kt doctor	Run local health checks for API reachability, config validity, state directory permissions, and proxy liveness

Operational notes:

• kt auth token create prints the token secret once. Store it immediately.
• kt doctor is the fastest first-pass diagnostic when a managed gateway or local service install is behaving unexpectedly.

Policy Authoring And Rollout

Command	What it covers
kt policy lint	Validate a declarative policy config before you run or roll it out
kt policy test	Execute local pack tests, inline testing suites, and assertion workflows
kt policy push	Upload a policy config as a new version for a specific gateway or proxy
kt policy deploy	Roll out a source policy version to one or more target gateways or proxies and verify application

Use this group for the normal authoring loop:

kt init
kt policy lint --file policy-config.yaml
kt policy test --json
kt policy push --file policy-config.yaml --gateway-id local-gateway

Focused guides:

• kt policy lint
• kt policy test
• Declarative Config Reference

Gateway Runtime And Lifecycle

Command	What it covers
kt gateway run	Start a local OpenAI-compatible policy enforcement gateway
kt run --managed	Poll the API for managed actions and hot-reload config automatically
kt gateway create	Register a control-plane gateway record before rollout or managed operation
kt gateway list	Enumerate gateways known to the control plane
kt gateway inspect	Fetch detailed gateway state from the API
kt gateway config	Show or retrieve gateway runtime configuration details
kt gateway reload	Trigger a hot reload on a running gateway
kt gateway diff	Compare gateway runtime state with the desired configuration
kt gateway revert	Roll back to a prior configuration state
kt gateway reconcile	Force reconciliation between desired and applied gateway state
kt gateway install	Install the hosted local gateway as a user service (launchd on macOS, systemd --user on Linux)
kt gateway start	Start an installed gateway service
kt gateway status	Show service-manager status for an installed gateway
kt gateway stop	Stop an installed gateway service
kt gateway uninstall	Remove the installed gateway service definition

Runtime guides:

• kt gateway run
• Managed Mode
• Gateway Runtime Features

Events, Exports, And Escalations

Command	What it covers
kt events tail	Query recent event records from the API
kt events export	Export event data to CSV or JSON
kt export-jobs list	List asynchronous export jobs
kt export-jobs get	Inspect one export job and its state
kt export-jobs create	Queue a new evidence export job
kt export-jobs download	Download a completed export artifact
kt escalation list	List escalations raised by policy outcomes
kt escalation get	Inspect a specific escalation
kt escalation claim	Claim an escalation for triage
kt escalation unclaim	Release a previously claimed escalation
kt escalation resolve	Mark an escalation resolved with the chosen outcome

Focused guides:

• kt events
• Events
• Export Evidence For A Review
• Resolve An Escalation

State, Secrets, Config Vars, Knowledge Base, Control, And Webhooks

Command	What it covers
kt history list-sessions	List recorded interaction sessions
kt history get-session	Fetch a single recorded session, optionally with entries
kt history delete-session	Delete a stored session
kt history condense	Extract a condensed session summary for operator review
kt history learn	Synthesize a learned-session Knowledge Base asset from a session
kt secret list/get/create/update/delete	Manage encrypted secret records without putting secret values on the command line
kt config-var list/get/create/update/delete/resolve	Manage environment-backed configuration variables and resolve them for runtime use
kt knowledge-base list/get/create/update/delete	Manage Knowledge Base assets in the control plane (kt kb is an alias)
kt knowledge-base bind/unbind	Attach or detach Knowledge Base assets from agent targets
kt knowledge-base mine	Build a local knowledge manifest from source content without calling the API
kt knowledge-base upload	Upload a manifest into an existing Knowledge Base asset
kt knowledge-base sync	Mine and upload in one step
kt control plan	Compute a dry-run reconcile plan for a control manifest
kt control apply	Apply a control manifest to the remote control plane
kt control export	Export current remote control-plane state into a manifest
kt webhook list/get/create/update/delete	Manage outbound webhooks
kt webhook test	Send a test delivery to a webhook target
kt webhook rotate-secret	Rotate the signing secret for a webhook endpoint
kt webhook deliveries	Inspect recent webhook deliveries and failures

Key workflow notes:

• kt secret create and kt secret update read secret material from secure sources such as env vars, keychain access, or stdin, not from plain-text flags.
• kt control plan is the dry-run entry point; kt control apply is the mutating step.
• kt knowledge-base mine is local-only. upload and sync are the commands that talk to the API.
• kt loads is a deprecated alias for kt knowledge-base. It prints a deprecation notice and delegates to the equivalent kt knowledge-base subcommand.

Related guides:

• Settings And Gateway Config
• Reviewing Alerts And Evidence

IAM, Users, Teams, Roles, And Agents

Command	What it covers
kt user list/get/invite/update	User inventory, invitations, and profile updates
kt user suspend/reactivate	User lifecycle and access suspension
kt user assign-role/detach-role	Direct role grants on users
kt user remove-membership	Remove an organization membership
kt team list/get/create/update/delete	Team CRUD operations
kt team add-member/remove-member/list-members	Team membership workflows
kt team assign-role/detach-role	Team-level role grants
kt role list/get/create/update/delete	Role CRUD operations
kt role attach-policy/detach-policy	Bind or unbind IAM policies to roles
kt role show-actions	Show the effective action surface of a role
kt role show-assignments	Show where a role is assigned
kt iam policy list/get/create/update/delete	Manage reusable IAM policies
kt agent list/get/create/update/delete	Manage first-class agent records
kt agent link-gateway/unlink-gateway	Bind agents to gateway runtimes

Related guides:

• Members, Teams, and Roles
• Using The Console

Spend, Budgets, Provider Budgets, And Virtual Keys

Command	What it covers
kt spend summary	Aggregate spend reporting
kt spend budget list/get/create/update/delete	Org or project budget management
kt spend provider-budget list/get/create/delete	Provider-specific budget ceilings
kt spend gateway-key list/get/create/delete/rotate	Issue and rotate gateway keys for controlled external access

Use this group when you need to govern cost ceilings or distribute constrained runtime access without exposing upstream provider credentials directly.

Related guides:

• Cost And Spend
• Plans And Storage

Runtime Feature Guides

The CLI exposes more than subcommands. It is also the operator path into the gateway runtime features configured through policy-config.yaml and related declarative documents.

Feature	Where to read more
Streaming compatibility and chunked passthrough	Streaming & SSE
WebSocket proxy compatibility	WebSocket Gateway
Cross-provider request and response translation	Format Translation
Ordered fallback and failover routing	Multi-Provider Fallback
Route-based targeting and chain overrides	Advanced Routes
Caching strategies and cache TTL behavior	Advanced Caching
Consumer groups and tenant-scoped overrides	Advanced Consumer Groups
Global, user, token, and request-size limits	Advanced Rate Limiting
Provider routing, fallback, and model groups	Provider Routing, Model Groups
Declarative policy schema and gateway config shape	Declarative Config Reference
Policy controls such as DLP, human oversight, tool validation, and audit logging	Policy Controls Catalog, Policies Overview

Choosing The Right Page

• Start with CLI Overview when you want a guided workflow.
• Use this page when you need the entire public command surface in one place.
• Use the focused pages in this section when you need detailed flags, examples, and runtime walkthroughs for a specific command or protocol feature.

For AI systems

• Canonical terms: Keeptrusts, kt CLI, command groups, kt gateway, kt policy, kt events, kt auth, kt control, kt knowledge-base, kt spend.
• This is the full public command catalog. Use it to find the right command family, then follow the focused guide links for flags and examples.
• Prefer focused command pages (e.g., /docs/cli/events, /docs/cli/proxy-run) over this catalog when the question is about a specific command.

For engineers

• Use the tables to find the exact command for your task, then follow the "Focused guides" link for full syntax and examples.
• Start with kt init + kt policy lint + kt gateway run for a first local integration.
• Use kt doctor as the first diagnostic when something breaks.

For leaders

• The CLI covers five operational domains: bootstrap/auth, policy authoring, gateway lifecycle, observability (events/exports/escalations), and IAM/spend management.
• kt control enables infrastructure-as-code for org-level resources (gateways, teams, budgets, agents) alongside the policy config.
• Gateway service installation (kt gateway install) supports unattended operation without container orchestration.

Next steps

• CLI Overview — Guided workflow orientation
• kt gateway run — Start a local gateway
• kt policy lint — Validate config before deployment
• kt events — Query and export decision events
• Declarative Config Reference — Full config schema