CLI Overview
Use the kt CLI to manage the public Keeptrusts workflow from the terminal.
Start here
| If you need to... | Start with |
|---|---|
| Bootstrap a config | kt init |
| Validate config and policy | Config Validation and Policy Lifecycle |
| Run a gateway | kt gateway run |
| Manage profiles and regions | Regions Overview and Region Commands |
| Connect an MCP client to Keeptrusts | Gateway MCP Surface |
| Inspect runtime outcomes | kt events and kt export-jobs |
| Review immutable audit evidence | kt trail |
| Manage tokens and auth | kt auth |
| Review spend and budgets | kt spend |
Public command groups
| Workflow | Commands |
|---|---|
| Bootstrap and diagnostics | kt init, kt doctor, kt config validate |
| Auth and tokens | kt auth ..., kt token ... |
| Policy authoring | kt policy lint/test/push/deploy for runtime config; kt policy diff/apply/evaluate/export for IAM |
| Gateway runtime | kt gateway ... |
| Profiles, regions, and locality | kt configure ..., kt regions ..., kt --region ... |
| Published-hostname MCP | Gateway-hosted /mcp surface on a published agent hostname |
| Events and evidence | kt events ..., kt trail ..., kt export-jobs ..., kt escalation ... |
| Cache and secrets | kt cache ..., kt secret ..., kt secrets ... |
| IAM and agents | kt user ..., kt team ..., kt role ..., kt iam policy ..., kt agent ... |
| Spend and budgets | kt spend summary, kt spend budget ..., kt spend provider-budget ... |
| Declarative control plane | kt control plan/apply/export |
This site focuses on the customer-facing command groups that are documented for public use.
Typical public workflow
export KEEPTRUSTS_API_URL="https://api.keeptrusts.com"
export KEEPTRUSTS_API_TOKEN="kt_your_authorized_token"
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
# Add a provider target and its referenced secret before serving model traffic.
# Replace docs-demo with an existing control-plane agent name.
kt gateway run --agent docs-demo --listen 127.0.0.1:41002 --policy-config policy-config.yaml
kt events tail --since 5m --json
Common global options
--lang and the compatibility --region shim are top-level global options.
The other flags below are command-specific; use them only when the selected
subcommand documents them.
| Flag | Meaning |
|---|---|
--lang | Select localized CLI output, overriding KT_LANG and the OS locale |
--json | Request JSON output when the command supports it |
--config | Choose a local CLI config file when the command supports it |
--api-url | Override the API base URL on supported API-backed commands |
--api-token | Override the API token on supported API-backed commands |
--profile | Choose a named CLI profile on supported API-backed commands |
--region | Set process-wide region context for local runtime surfaces that still honor the compatibility shim; API commands usually expose their own --region option |
The default CLI config file path is ~/.keeptrusts/config.yaml.
Use ~/.keeptrusts/config.yaml for CLI profile defaults such as the requested region. Use policy-config.yaml for gateway runtime and provider routing, including locality-sensitive behavior. kt regions current helps you inspect the former; it does not rewrite the latter.
Key environment variables
| Variable | Purpose |
|---|---|
KEEPTRUSTS_API_URL | Keeptrusts API base URL |
KEEPTRUSTS_API_TOKEN | Direct CLI credential or connected-runtime service credential, depending on the process; it is not automatically the application bearer token for model requests |
KEEPTRUSTS_REGION | Compatibility process-wide region context for surfaces that still honor it; it is not the API-command region fallback |
KEEPTRUSTS_OPENAI_API_KEY | Recommended OpenAI provider secret name; reference this exact name through secret_key_ref.env |
KEEPTRUSTS_CONFIG | Path to a local CLI config file |
Provider credentials are resolved only from the exact environment or secret
store name declared by the target. The gateway does not implicitly fall back
to generic provider variables such as OPENAI_API_KEY.