tetrate CLI
tetrate is the command-line interface for Tetrate Agent Router, one tool across both product lines, with Agent Router's commands under tetrate agentrouter. It collapses three manual steps (image sync, pull-secret creation, and Helm deployment) into one invocation.
Commands
| Command | Description |
|---|---|
tetrate agentrouter dataplane install | Install the Agent Router data plane |
tetrate agentrouter dataplane uninstall | Tear down the Agent Router data plane (cluster-only; reverses install) |
tetrate agentrouter dataplane upgrade | Upgrade an existing Agent Router data plane release (HA-safe, atomic) |
tetrate agentrouter dataplane ingress install | Install serve gateway resources (GCP, Azure, or AWS) |
tetrate agentrouter dataplane ingress config init | Generate a starter gcp-gateway.json from a domain and project ID |
tetrate agentrouter dataplane ingress config lint | Lint a gcp-gateway.json config (hermetic, CI-safe) |
tetrate agentrouter dataplane mcp install | Deploy MCP server pods on a customer cluster |
tetrate agentrouter dataplane mcp list | Show deployed MCP server status |
tetrate agentrouter dataplane mcp enable | Register a deployed MCP server in the management plane's MCP catalog |
tetrate agentrouter dataplane mcp uninstall | Remove the tars-mcp Helm release |
tetrate agentrouter api guardrails providers | Register, update, and list guardrail providers, and store a provider's credential with set-secret |
tetrate agentrouter integrate | Configure local coding tools (Claude Code, Codex, and others) against the Agent Router gateway |
Quick start
# Print Helm values without touching the cluster
tetrate agentrouter dataplane install identity.json --print-helm-values
# Full install
tetrate agentrouter dataplane install identity.json
# Sync images to a private registry then install
tetrate agentrouter dataplane install identity.json \
--image-sync myregistry.example.com
# Sync + create pull secret + install in one command
echo "user:password" | tetrate agentrouter dataplane install identity.json \
--image-sync myregistry.example.com \
--image-pull-secret-stdin
Identity file
tetrate accepts the service-account file in both formats produced by the
management plane:
Wrapped format (standard):
{
"serviceAccount": { ... },
"checksum": "664b355c...",
"checksumAlgorithm": "sha256"
}
Naked format (direct service account JSON):
{
"type": "service_account",
...
}
Use tetrate agentrouter identity wrap to convert a naked file to the wrapped format.
Gateway config schema
For tetrate agentrouter dataplane ingress install, the config file shape depends on the provider:
gcp-gateway.jsonschema:--type gcpazure-gateway.jsonschema:--type azure--type awstakes no config file; it is configured entirely by flags
Version
tetrate --version
Exit codes
From 0.8.0 the tetrate command gives each kind of failure its own exit code, so a script can tell a refusal from a partly applied change without reading the message:
| Exit code | Meaning |
|---|---|
0 | Success: the command did what it was asked |
1 | Runtime failure: something went wrong, and the message says what |
2 | Usage error: the invocation was wrong, or wrong for where it ran, such as a missing terminal to prompt on |
3 | Refused before acting: a precondition failed and nothing was changed, so the command is safe to fix and retry |
4 | Failed while acting: the cluster had begun to change, so it may be partly applied and is inspected before a retry |
Codes 0, 1, and 2 keep their meanings. Before 0.8.0, a refusal and a failure that had already changed the cluster both exited 1. A command stopped by a signal exits 3 when nothing had been changed yet, and 4 when the change had begun.
The tare, tars, and admin names keep their earlier contract: every failure exits 1, so a script that branches on their exit status keeps working. The one change under those names is a mistyped subcommand: from 0.8.0 it fails with 1 (and with 2 under tetrate), where it previously printed help and exited 0.
A pipeline that treats any non-zero exit as a failure needs no change. One that retries does not retry on 3, and treats 4 as a cluster that was partly changed rather than untouched. tetrate agentrouter doctor adds its own rule for findings, set by --fail-on; see Reading tetrate agentrouter doctor output.
Command mapping
The tare, tars, and admin names still run, and each prints the tetrate command that replaces it. A legacy command maps to its tetrate spelling as follows; a subcommand below a mapped group keeps its own name, so tare api policy rate-limits list is tetrate agentrouter api policy rate-limits list.
| Legacy command | tetrate command |
|---|---|
tare install, tare upgrade, tare uninstall | tetrate agentrouter dataplane install, upgrade, uninstall |
tare precheck, tare smoke | tetrate agentrouter dataplane precheck, smoke |
tare serve <command> | tetrate agentrouter dataplane <command> |
tare gateway <command>, tare serve gateway <command> | tetrate agentrouter dataplane ingress <command> |
tare install-gateway | tetrate agentrouter dataplane ingress install |
tare mcp <command> | tetrate agentrouter dataplane mcp <command> |
tare manage <command> | tetrate agentrouter manage <command> |
tare manage gateway <command> | tetrate agentrouter manage ingress <command> |
tare dataplane, identity, doctor, audit, versions, api, integrate, run | The same path under tetrate agentrouter, for example tetrate agentrouter doctor |
tars serve install | tetrate agentrouter dataplane install (--proxy-url is removed) |
tars sa check, token, wrap, edit | tetrate agentrouter identity check, token, wrap, edit |
tars ping | tetrate agentrouter manage ping |
tars helm, tars images | tetrate agentrouter dataplane helm, images |
admin <command> | tetrate agentrouter admin <command> |
admin images copy | tetrate agentrouter manage images copy |
Environment variables take a TETRATE_ prefix: TARS_API_KEY is TETRATE_API_KEY (the inference key), API_KEY is TETRATE_ADMIN_API_KEY (the admin credential), and each TARE_* variable is the same name with TETRATE_ in place of TARE_. The old names still work while the new one is unset, and warn once on stderr.
Generated command reference
Every command has a generated reference page derived from its --help output, for example tetrate agentrouter dataplane install. The legacy spellings keep their own generated pages, such as tare install, until the old names are removed. The generated pages carry the authoritative flag lists; the hand-authored pages in this section cover workflows, defaults, and troubleshooting.
Where to go next