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 want one high-level map of the documented CLI.

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 auth login`	Sign in and store a reusable CLI session
`kt auth logout`	Remove stored session credentials for the active profile
`kt auth whoami`	Show the active identity and API access context
`kt auth token create`	Mint a scoped automation token backed by IAM role bindings
`kt auth token list`	List issued auth tokens
`kt auth token revoke`	Revoke a previously issued auth token
`kt doctor`	Report API connectivity, config readability, state-directory access, and local supervisor records
`kt config validate`	Parse and validate a declarative gateway configuration without starting a runtime

Policy authoring and rollout

Command	What it covers
`kt policy lint`	Validate a runtime config or IAM policy document
`kt policy test`	Execute local pack tests and inline `testing` suites
`kt policy push`	Upload a policy config as a new version for a gateway
`kt policy deploy`	Roll out a source policy version to one or more target gateways and verify application
`kt policy diff`	Compute a dry-run reconcile plan for IAM policy documents
`kt policy apply`	Reconcile reviewed IAM policy documents to the control plane
`kt policy evaluate`	Simulate an action and resource KRN against local or selected remote IAM policies
`kt policy export`	Export selected or all remote IAM policies to YAML or JSON

Use this group for the normal authoring loop:

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

The command family manages two document types. Runtime policy-config.yaml uses lint, test, push, and deploy; IAM policy documents use lint, diff, apply, evaluate, and export. See Policy Lifecycle before automating either path.

Gateway runtime and lifecycle

Command	What it covers
`kt gateway run`	Start a local governance gateway for the supported public request families
`kt gateway check`	Resolve config, provider credentials, routing, and the policy chain without starting a server
`kt gateway create`	Create a local supervisor definition with the listen and upstream settings you want to manage
`kt gateway list`	List local gateways, or remote gateways with `--remote`
`kt gateway inspect`	Inspect a named local gateway and optional recent lifecycle history
`kt gateway config`	Query a running gateway config endpoint by URL
`kt gateway reload`	Ask a running gateway at a specific URL to reload
`kt gateway diff`	Compare the current named gateway state with its saved local service state
`kt gateway revert`	Ask a running gateway at a specific URL to revert
`kt gateway reconcile`	Reconcile a named gateway, or every known gateway with `--all`
`kt gateway install`	Install a local gateway as a user service
`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
`kt gateway upgrade plan/apply/status/rollback`	Plan, apply, inspect, or roll back a local runtime binary upgrade

Focused guides:

Profiles, regions, and locality

Command	What it covers
`kt configure set region <region> --profile <profile>`	Persist a profile-scoped default region in `~/.keeptrusts/config.yaml`
`kt configure get region --profile <profile>`	Read the configured default region for one profile
`kt configure list-profiles`	Show known profile names from config and stored credentials
`kt regions list`	Discover available regions with sovereignty class and API endpoints
`kt regions use`	Write the default region for the active CLI profile
`kt regions switch`	Alias for `use`
`kt regions current`	Show the resolved region, winning source, resolved API endpoint, and requested scope
`kt regions status`	Show detailed status for each region

Use a command's own --region <region> option for API-backed operations. The top-level kt --region <region> ... form is a compatibility shim for local gateway/runtime surfaces that still read process-wide context.

kt regions list also supports --enabled, --disabled, --group <group_key>, --sovereignty-class <class>, and --json.

Removed config commands

kt config show, kt config migrate, and kt config diff are no longer part of the public CLI surface. Use kt configure ... for profile defaults, kt regions ... for locality inspection, and the command-specific diff surfaces such as kt gateway diff or kt policy diff where those workflows still exist.

Declarative-config precedence

Use kt configure ... and kt regions ... to manage the requested region for API-backed CLI commands. Use policy-config.yaml for gateway and provider locality. The CLI profile default does not override runtime routing declared in the policy config.

Published-hostname MCP

This surface is not a separate kt subcommand. The gateway serves MCP directly from a published agent hostname at /mcp.

Use Gateway MCP Surface for the current transport details, capability limits, and the distinction between the hosted MCP surface, runtime MCP bridge targets, and declarative tool-server metadata.

Events, exports, and escalations

Command	What it covers
`kt events tail`	Query recent event records from the Keeptrusts API
`kt events export`	Export event data directly as CSV or JSON
`kt trail lookup`	Query immutable Trail events by request ID or audit filters
`kt trail verify`	Verify a nonempty bounded Trail window: digest-link checks by default, or event hash, sequence, and intra-window link checks with `--deep`
`kt trail export`	Export a filtered Trail window to JSON, JSONL, CSV, or gzip
`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

History, secrets, cache, and control

Command	What it covers
`kt history list-sessions/get-session/delete-session`	Browse, inspect, and delete governed history sessions
`kt history export/tag/search/share/replay/stats`	Export, organize, inspect, replay, and summarize governed history
`kt history learn`	Request server-side learning for one selected history session, or preview its source entries
`kt history condense`	Generate a condensed session summary for review or handoff
`kt secret list/get/create/update/delete`	Manage hosted secret records without putting secret values on the command line
`kt secrets add/status`	Manage local credential resolution for provider targets
`kt cache stats/list/inspect/clear`	Inspect or clear the response-cache backend selected by the current environment
`kt control plan`	Compute a dry-run reconcile plan for a control manifest
`kt control apply`	Apply a control manifest to the Keeptrusts API
`kt control export`	Export current remote control state into a manifest

Workflow notes:

Use kt secret ... for hosted secret records.
Use kt secrets ... for local keychain or environment credential resolution checks.
Use kt cache ... with the exact gateway cache environment; detailed entry and counter views are filesystem-specific.
Use kt control plan before apply, and pair every apply --prune with a reviewed plan --prune.

IAM, users, teams, roles, policies, and agents

Command	What it covers
`kt user ...`	User inventory, invitations, lifecycle, and direct role assignment
`kt team ...`	Team CRUD operations, membership, and team-level role grants
`kt role ...`	Role CRUD operations plus policy attachment and effective-action inspection
`kt iam policy ...`	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

Focused guides:

Spend, budgets, provider budgets, and API tokens

Command	What it covers
`kt spend summary`	Aggregate spend reporting
`kt spend budget ...`	Org, team, user, or key budget management
`kt spend provider-budget ...`	Provider-specific budget ceilings
`kt token ...`	Governed API token lifecycle, including create, update, clone, revoke, rotate, validate, and code exchange

Use this group when you need to manage cost ceilings, publish bounded access, or rotate customer-facing gateway credentials.

Runtime feature guides

The CLI also drives the gateway runtime behaviors 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
Connected relay transport for NAT-bound gateways	Connected Gateway Relay
Cross-provider request and response translation	Format Translation
Ordered fallback and failover routing	Multi-Provider Fallback
Route-based targeting and chain overrides	Routes and Consumer Groups
Caching behavior and runtime defaults	Runtime Configuration
Cache inspection and maintenance	Local Response Cache
Provider routing, fallback, and model groups	Providers Configuration, Data Routing Policy
Rate limits	Rate Limits Configuration
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

Bootstrap, auth, and diagnostics​

Policy authoring and rollout​

Gateway runtime and lifecycle​

Profiles, regions, and locality​

Published-hostname MCP​

Events, exports, and escalations​

History, secrets, cache, and control​

IAM, users, teams, roles, policies, and agents​

Spend, budgets, provider budgets, and API tokens​

Runtime feature guides​

Next steps​