Use the Agentic Data Plane CLI

The Agentic Data Plane CLI is an rpk managed plugin. Install rpk first (see Install or Update rpk), then install the plugin:

Update the plugin later with rpk ai upgrade, and remove it with rpk ai uninstall.

The CLI tells you when a newer version is published. While a command runs, it checks in the background for a new version, no more than once a day, and prints a notice on stderr naming that version and the command that upgrades it. The notice also appears after a command that fails with an error or prints help, because an outdated CLI often explains those results.

The check never delays a command. A check still running when the command ends is canceled and tried again an hour later. It runs only when both standard output and standard error are terminals, so scripts, pipes, -o json captures, and agents never see the notice, and it is skipped in continuous integration. It never suggests an older version. To turn it off, set RPAI_NO_UPDATE_CHECK=1.

The rpk ai command is self-contained: it has its own login and its own environment selection, independent of any rpk cloud session. You sign in once, choose an Agentic Data Plane environment, and rpk ai targets that environment’s AI Gateway for every command.

For the full setup walkthrough, including token expiry behavior and the supported environment variables, see Use rpk ai for local development.

To target a different AI Gateway URL for a single command without switching environments, pass --rpai-endpoint:

This overrides the selected environment’s AI Gateway URL for that one command; the flag is not bound to an environment variable. For a local or manual gateway you use repeatedly, define it once as an environment with rpk ai env add:

If you would rather not look a command up, Agentic Data Plane can hand you the one you need. Most resource pages carry a Use with rpk ai button in the page header. It opens a panel that walks you through installing the CLI for your operating system, signing in, and selecting the environment you are looking at, then prints a ready-to-run command for the resource in front of you.

The last step has a goal selector. Pick what you want to do, such as listing the resource, inspecting it, or starting and stopping it, and the panel shows the command for that goal with the resource’s own name already filled in. Related commands appear in the same list as a --help invocation, so you can read their flags before you run them. Each setup step remembers whether you collapsed it, so you can fold away the steps you’ve finished and a later visit opens with them still folded.

Each Agentic Data Plane resource has its own command group, and each group supports the standard create, get, list, update, and delete actions. The model catalog and the audit log are read-only.

For example, to create and inspect an LLM provider:

The positional argument (openai here) is the provider’s name. Pass --enabled, because a provider created without it is disabled and rejects every request. Pass at least one --provider-models value, because a provider needs at least one model. The provider type comes from which configuration flag group you use: --openai-config., --anthropic-config., --google-config., --bedrock-config., or --openai-compatible-config.*. Setting flags from two groups is an error. The --openai-config.api-key-ref flag names a secret already stored in Agentic Data Plane. The CLI never takes a raw API key, so secrets stay out of your shell history and out of any file you commit.

Trigger commands take two different arguments, because a trigger belongs to an agent. The create and list commands take the parent agent, and get, update, delete, and runs take the trigger’s full resource name, agents/<agent-id>/triggers/<trigger-id>, which list prints:

The runs command lists a schedule trigger’s recorded runs, newest first. For what triggers do and how to configure them, see Trigger Agents.

Secret commands never print a stored value, and they take the secret’s bare ID or its secrets/<secret-id> resource name. Pass a new value with --value-file, which reads a file, or with --value-file=-, which reads standard input. Either way, the credential stays out of your shell history and out of the process list. Write it with the =, because rpk ai drops a bare - after a flag and --value-file - fails.

For example:

An update that passes no value keeps the stored one, and --tag merges onto the tags the secret already has rather than replacing them. Use --remove-tag to drop one. For the full CLI workflow, see Manage secrets with rpk ai. That page also covers what secrets are and who can manage them.

To create, update, and delete resources declaratively from YAML manifests instead of imperative flags, see Manage Resources with GitOps.

Besides managing an MCP server’s configuration, rpk ai mcp-server connects to a server and inspects what it serves at runtime, the same surface the Inspector shows in the UI. Use it to check a server from a script or a terminal, without opening the UI.

In these commands, handbook is the MCP server’s name. ping reports the MCP protocol version the two sides negotiated and the capabilities the server advertises. Start with it when a server isn’t behaving. A server that answers ping is reachable and authenticated.

A server serves only what it advertises, so a command for a capability the server doesn’t offer fails saying so rather than returning an empty list. Reading a resource goes through the MCP server, which returns the resource’s text or its base64-encoded binary contents along with the response metadata. The CLI never fetches the URI itself. Getting a prompt resolves it and prints its messages, without sending them to a model. The --args value is a JSON object whose values are all strings.

The ping, resources, resource-templates, and prompts commands print JSON, or YAML with -o yaml. The tools list command prints a table unless you pass -o json or -o yaml. The list commands return one page at a time. Read nextCursor from the JSON or YAML output and pass it to --cursor to get the next page. Each command accepts --timeout, which covers the connection and the request together and defaults to 30 seconds.

Three read-only command groups return the same data the observability and cost pages show, so you can pull it into a script, a dashboard, or a report.

The rpk ai trace commands take one flag for each field you filter on. Every listing covers a time range, so --since is required. Give it a timestamp, or a duration ago such as 24h or 7d. Add --until to end the range earlier than now. The range can span at most 30 days. Narrow the list further with --status, --errors, --agent, --user, or --conversation. You can repeat --status and --user to match any of several values, but you can’t combine --status with --errors. Pass a raw filter expression with --filter to narrow the list beyond the other flags. It can’t repeat a field that another flag already sets, so --agent support --filter 'agent_uid = "…​"' fails instead of narrowing the list. --limit caps how many traces are printed, 50 by default and 1,000 at most, and the command reads as many pages as it needs to fill it.

Pass rpk ai trace get the trace ID that rpk ai trace list prints, or a link to the trace copied from the Agentic Data Plane UI, which also tells the command where in time to look. Run rpk ai trace span list to print a trace’s spans, and add --ids for the span IDs that rpk ai trace span get takes. To make a script fail on a run that didn’t finish cleanly, pass --fail-on-error to rpk ai trace get. It exits with code 4 when the trace ended in error or stayed incomplete.

The rpk ai spending and rpk ai agent-network commands instead take their request fields as dotted flags, or a whole request from a file with -f. A time range is two flags:

In -o json and -o yaml, these two groups print the whole response, pagination token included, rather than only the rows. Pass that token back with --page-token to read the next page.

Run rpk ai docs to read the published Agentic Data Plane documentation without leaving your terminal. The command needs no sign-in and no selected environment, because it reads the public documentation site.

With no path, the command opens a searchable picker in an interactive terminal, and prints an index when its output is piped. A path is the page’s path on the documentation site, such as cli or connect/coding-agents, and a full documentation URL works too.

The search subcommand matches page titles, paths, and descriptions, not page bodies. It returns up to 20 results by default. Use --limit to change that, up to 100.

These flags change what the command does with a page:

Responses are cached for an hour. If a request fails temporarily, the command prints the cached copy with a warning, and marks it as stale in -o json and -o yaml output. The documentation it reads tracks the published site rather than your installed CLI version, so check --help for the flags your installation supports.

Every list and get command honors -o (--format):

Set a default for the session with the RPAI_FORMAT environment variable. The -o flag always wins when both are set.

A script or continuous integration job can tell why a command failed from its exit code:

Separating exit 3 from exit 1 lets a scheduled job re-authenticate instead of treating an expired token as a broken command. Re-authenticate once on exit 3. If the command exits 3 again after a fresh login, the cause is a missing permission rather than an expired token, so grant the permission the operation needs. See Roles and Permissions Reference.

Pass --rpai-verbose (or -v) to log one line per HTTP request to stderr, with the method, URL, response status, and latency:

Use it to find out which endpoint a command called and how long the call took. Request and response bodies, headers, and your bearer token never appear in the output, so verbose output is safe to paste into a support ticket. Set the RPAI_VERBOSE environment variable to turn it on for every command in the session.