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.
Warning
Install agctl, the command-line tool that you use to inspect and debug agentgateway and to manage standalone configuration resources, virtual keys, and recorded LLM traffic.
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, collect CPU and heap profiles, 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 proxy profile | Collect a CPU or heap pprof profile from an agentgateway proxy and write it to a file. |
agctl controller log | Get or set log levels for the agentgateway controller at runtime. |
agctl catalog | Manage the model catalogs that price LLM requests, including importing catalog data from supported pricing sources. |
agctl migrate | Migrate agentgateway resources to newer configurations. |
agctl standalone | Manage the configuration resources, virtual keys, budgets, and recorded LLM traffic of a standalone agentgateway. For more information, see Manage standalone agentgateway. |
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.
Manage standalone agentgateway
Use agctl standalone to manage agentgateway that runs as a binary, in Docker, or through the standalone Helm chart. The commands call the configuration and observability APIs of the gateway. They do not manage Kubernetes Gateway API resources.
| Command | Description |
|---|---|
agctl standalone get | List configuration resources, or inspect a resource by name or ID. |
agctl standalone apply | Create or update resources from YAML or JSON resource documents. |
agctl standalone delete | Remove a configuration resource. |
agctl standalone keys | List LLM virtual keys. To generate a key, use agctl standalone keys create. |
agctl standalone budgets | Check the usage of per-key dollar and token budgets. |
agctl standalone logs | Query or follow the LLM request logs that agentgateway stores in a database. |
agctl standalone analytics | Summarize recorded requests, tokens, cost, and performance. |
To get started, connect agctl to your gateway. Then, manage virtual keys or view request logs.
Note
The agctl standalone logs command reads the LLM requests that are stored in the database. To change the log level of the running proxy, use agctl proxy log instead.
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 -fsSL 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 --helpNote
Use the same agctl 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"