What is an agent-readable CLI? Capabilities and discovery

By

An agent-readable CLI explains its tasks, commands, and output so a coding agent can use it. See a real capabilities command and where permissions apply.

An agent-readable CLI is a command-line tool that gives a coding agent enough information to discover its tasks and run the right command. Clear help, structured output, and explicit errors make that possible.

Help your coding agent find installed CLI tools walks through the workflow with real output. Flavio’s tools use a capabilities command for discovery. This is a convention for those tools, rather than a command every CLI implements.

How discovery works

The agent reads a tool’s description, checks the relevant command, then runs it within its permissions. It reads the result before deciding what to do next.

Discover and use an installed CLIThe agent finds a tool, reads its capabilities and command help, runs an allowed command, then checks the output.Find a toolRead capabilitiesCheck command helpRun allowed commandRead result

Agent-readable CLIs in coding tools

Claude Code documents access to terminal commands in How Claude Code works. Cursor documents shell execution in its Terminal tool.

Codex’s approvals and security guide and Grok Build’s permissions guide describe the boundaries around commands. Discovering a command doesn’t authorize its side effects. The tool must also be installed in the environment where the agent runs.

Details checked against each vendor’s documentation in November 2026.

A real example

Ask CLI Tools Cabinet for Searchglass’s capabilities:

clitools capabilities searchglass --json

The returned manifest identifies searchglass and describes reading Google Search Console performance, properties, sitemaps, and index status. It lists commands such as searchglass sites and searchglass auth status --check.

The manifest describes what the tool can do. A data query still needs Searchglass’s own completed Google login.

When to use an agent-readable CLI

Use one when an installed tool already handles your task. Read its help before writing a replacement script or guessing flags.

Pitfalls

Check top-level help before trying capabilities on an unfamiliar program. Some agent CLIs interpret an unknown word as a prompt and start a session.

A local tool catalog describes this machine. A cloud agent may have different commands installed, and a sandbox can prevent a discovered command from reaching files or the network.

  • Tool calling: Tool calling is when a model names a function and its arguments, and the app runs it. How Claude Code, Codex, Cursor and Grok Build take that step.
  • Headless mode: Headless mode runs a coding agent from a script, with no chat UI. How claude -p, codex exec, the Cursor CLI and grok -p differ on permissions.
  • Permission modes: Permission modes decide what a coding agent can do without asking. The modes in Claude Code, Codex, Cursor and Grok Build, and what YOLO mode really skips.

All AI glossary entries →

Want me to talk about your product? You can sponsor this site.