For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Install agctl
Install the agctl command-line tool for inspecting and debugging agentgateway.
Install agctl, the command-line tool that you use to inspect and debug agentgateway.
About
agctl is the agentgateway command-line interface. Use agctl to inspect the configuration that an agentgateway proxy has loaded, capture detailed traces of requests as the proxy handles them, and manage proxy and controller log levels. The CLI works against agentgateway running in Kubernetes or as a standalone binary on your workstation.
agctl includes the following subcommands.
| Command | Description |
|---|---|
agctl proxy trace | Capture a tap-style trace to analyze a copy of the next request that an agentgateway proxy handles. Renders the trace in an interactive, text-based terminal user interface (TUI) by default. Alternatively, you can format the output as JSON for piping to other tools. |
agctl proxy config | Retrieve the runtime configuration that an agentgateway proxy has loaded, including binds, listeners, routes, backends, workloads, and services. |
agctl proxy log | Get or set log levels for the agentgateway proxy at runtime. |
agctl controller log | Get or set log levels for the agentgateway controller at runtime. |
agctl version | Print version information for the agctl CLI. |
agctl completion | Turn on autocompletion for your shell in bash, zsh, fish, or powershell. |
For a complete list of subcommands and flags, see the agctl CLI reference.
Before you begin
Make sure that you have Graphviz installed if you plan to use agctl for profile investigation.
If you choose to build agctl from source, you must also install Go 1.22 or later and Git.
Install agctl
Download the agctl binary for your platform from the releases page or build it from source.
Download the pre-compiled binary:
curl -sL https://github.com/agentgateway/agentgateway/releases/latest/download/agctl-linux-amd64 -o agctl
chmod +x agctl
sudo mv agctl /usr/local/bin/agctlVerify the installation
agctl --helpExample output:
agctl controls and inspects Agentgateway resources
Usage:
agctl [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
controller Inspect and manage the Agentgateway controller
help Help about any command
proxy Inspect and manage the Agentgateway proxy
version Print agctl version information
Flags:
-h, --help help for agctl
-k, --kubeconfig string kubeconfig
Use "agctl [command] --help" for more information about a command.Enable shell completion
agctl ships with an autocompletion script for bash, zsh, fish, and powershell. Source the script for your shell to get tab-completion of subcommands, flags, and resource names.
Add the completion script to a directory on your $fpath. The following example creates one and writes the script to it.
mkdir -p ~/.zsh/completions
agctl completion zsh > ~/.zsh/completions/_agctlAdd the directory to $fpath and load completion in your ~/.zshrc.
fpath=(~/.zsh/completions $fpath)
autoload -U compinit && compinitUpgrade agctl
To upgrade agctl, replace the binary with the new version following the same steps as installation.
If you built from source, pull the latest changes and rebuild.
cd agentgateway
git pull
go install ./controller/cmd/agctlVerify the new version.
agctl --helpagctl version as the agentgateway version that you run in your cluster. Slight skews within minor versions typically work, but compatibility across major versions is not guaranteed.Uninstall agctl
To uninstall agctl, remove the binary from your system. For example:
# If installed to /usr/local/bin
sudo rm /usr/local/bin/agctl
# If installed via GOBIN
rm "$(go env GOPATH)/bin/agctl"