Tetrate CLI

The tetrate CLI connects clusters to Tetrate Patch Service and installs managed products onto them. This page lists every command and the arguments and flags each one accepts. To get the CLI, see Installing the Tetrate CLI; for the procedures that use it, see Connecting Clusters.

The console always offers the latest build, and this page describes that build. Run tetrate <command> --help to see the help of the build you have installed.

Command	What it does
tetrate onboard	Connects clusters to the Patch Service by installing the agent.
tetrate manage	Installs a managed product onto clusters, with the agent.
tetrate login	Signs in and caches the credentials.
tetrate logout	Deletes the cached credentials.
tetrate logs	Shows the log of the most recent run.
tetrate version	Prints the CLI's version.
tetrate completion	Generates a shell completion script.

Global Flags

Every command accepts these flags.

Flag	Description	Default
--no-browser	Signs in without opening a browser on this machine: the CLI prints a code and a URL to open on another device. --no-browser=false insists on opening a browser here.	Detected from the environment, or TPS_NO_BROWSER
-h, --help	Prints the help of the command.

There is no need to sign in before running a command: the first command that needs the Patch Service signs you in.

Environment Variables

Variable	Description
TPS_NO_BROWSER	true or false, with the same meaning as --no-browser. The flag wins when both are given. Any other value is refused: Error: TPS_NO_BROWSER must be true or false, not "maybe".
KUBECONFIG	Where onboard and manage read your kubeconfig from, unless --kubeconfig is given.

tetrate onboard

tetrate onboard [flags]

Connects clusters to the Patch Service: registers each one and installs the agent into it. Nothing else is installed and no workloads are changed.

With no target, it looks at every context in your kubeconfig, shows a plan of what it would do, and asks which clusters to connect. Only the current context starts selected, and a selects them all. Each cluster is registered under the name its kube context suggests, reduced to a DNS-1123 label; if another cluster already holds that name, it is registered under a name derived from it, and the summary says which. See Connecting Clusters.

A run given any of the agent settings flags reinstalls the agent on clusters that are already connected, with the settings given, the defaults for any left out, and the agent version this CLI installs. A run given none skips connected clusters, unless one is named with --kubecontext, which always reinstalls it. See Changing the Settings of a Connected Cluster.

Flag	Description	Default
--kubeconfig <path>	The kubeconfig file to read contexts from.	KUBECONFIG, then ~/.kube/config
--kubecontext <context>	Connects only this context, without the plan or the prompt.	Choose from every context
--yes	Connects every eligible cluster without prompting, which an unattended run needs.
--agent-version <version>	The agent version to install.	0.4.4
--watch-namespaces <ns>,<ns>	The namespaces the agent watches, comma-separated or repeated. Each must be a DNS-1123 label.	tetrate-dataplane-system, envoy-gateway-system, envoy-ai-gateway-system
--watch-all-namespaces	Has the agent watch every namespace in the cluster. Cannot be combined with --watch-namespaces.
--registry-alias <registry>=<prefix>	A registry mirror you pull Tetrate's images through, such as docker.io=registry.example.com/dockerhub. Repeatable, one per registry.
--extra-repository <repository>[=<upstream>]	A repository to treat as Tetrate's, for a mirror that renamed repositories rather than prefixing them, optionally naming the Tetrate repository it copies. Only entries that name it are scanned for CVEs. Repeatable.

The agent settings flags are checked before you are signed in, so an invalid value fails at once. Discovering Images from a Private Registry explains how to work out the mirror flags.

# Choose from every context in your kubeconfig.
tetrate onboard

# Connect one cluster and nothing else.
tetrate onboard --kubecontext prod

# Connect every eligible cluster, with no prompt.
tetrate onboard --yes

# Work from a different kubeconfig.
tetrate onboard --kubeconfig ~/.kube/prod.yaml

# Watch two namespaces of your own, through a Docker Hub mirror.
tetrate onboard --watch-namespaces gateways,edge \
  --registry-alias docker.io=registry.example.com/dockerhub

tetrate manage

tetrate manage <product> <environment> [flags]

Installs a managed product's data plane onto clusters and registers them with the Patch Service, so they receive automated patches and upgrades. The agent is installed with the product. It requires the managed data plane; to connect a cluster without a product, use tetrate onboard.

Argument	Description
<product>	A product: a top-level directory of your GitOps repository, such as teg.
<environment>	An environment of that product: a directory under <product>/envs/ in your repository, such as default.

Both arguments are required. Choosing clusters, naming them, and the plan work as for tetrate onboard. See Installing a Managed Product.

Flag	Description	Default
--kubeconfig <path>	The kubeconfig file to read contexts from.	KUBECONFIG, then ~/.kube/config
--kubecontext <context>	Installs onto only this context, without the plan or the prompt.	Choose from every context
--yes	Installs onto every eligible cluster without prompting.

The agent installed with a product takes its settings from agent/values-customer.yaml in your repository, so manage has no agent settings flags.

# Choose which clusters get the teg product's default environment.
tetrate manage teg default

# Install onto one cluster and nothing else.
tetrate manage teg default --kubecontext prod

# Install onto every eligible cluster, with no prompt.
tetrate manage teg default --yes

tetrate login

tetrate login [flags]

Signs in to the Patch Service and caches the credentials, so later commands run without prompting. It opens a browser to sign in; on a machine without one, such as an SSH session or a container, it prints a code and a URL to open on any other device, and carries on once you have signed in there. Use --no-browser to insist on the code, or --no-browser=false to insist on the browser.

Signing in explicitly is optional: every command that needs the Patch Service signs you in when needed. The command takes only the global flags.

# Sign in, opening a browser if this machine has one.
tetrate login

# Sign in from a terminal with no browser, using a code entered elsewhere.
tetrate login --no-browser

tetrate logout

tetrate logout [flags]

Deletes the cached credentials, if any. It does not revoke them: the next command that needs the Patch Service signs you in again. The command takes only the global flags.

tetrate logs

tetrate logs [flags]

Prints the log of the most recent run. Every command that talks to the Patch Service or to a cluster records what it does in a log file of its own, without printing it to the terminal, and a command that fails prints where its log is. Include that file when you report a problem: logs record what was called and what failed, never credentials, tokens, or the contents of requests and responses.

Flag	Description
--path	Prints the path of the most recent log instead of its contents.
--list	Lists the paths of every kept log, newest first.

# Print the log of the last run.
tetrate logs

# Print only its path, for example to attach it to a support request.
tetrate logs --path

# List the logs that are kept, newest first.
tetrate logs --list

tetrate version

tetrate version

Prints the CLI's version and build details as JSON. Include it when you report a problem.

tetrate completion

tetrate completion <shell>

Prints a completion script for bash, zsh, fish, or powershell, so your shell completes tetrate commands and flags. Run tetrate completion <shell> --help for how to load it in that shell. For example, in the current zsh session:

source <(tetrate completion zsh)

Files and Exit Status

Path	What it holds
~/.config/tetrate-data-plane/credentials.json	The cached credentials. tetrate logout deletes them. Under $XDG_CONFIG_HOME/tetrate-data-plane when that is set.
~/.local/state/tetrate-data-plane/logs/	One log per run, of which the 20 most recent are kept. Under $XDG_STATE_HOME/tetrate-data-plane when that is set.

Every command exits with 0 on success and 1 on failure. A run of onboard or manage exits with 1 when any cluster failed, even if others succeeded.

Next Steps

• Install the Tetrate CLI from the console.
• Connect your first cluster with tetrate onboard.
• Connect clusters, including choosing the agent's settings and installing a managed product.