Giving agents hands: a CLI that lets coding agents explore any API

The Problem: APIs at Scale

Large enterprise platforms accumulate APIs the way cities accumulate roads. Start with a few clean endpoints, add microservices and gateway layers over time, and before long you have 2,000+ operations spanning 100+ domains — accounts, tickets, conversations, deployments, permissions, analytics, AI services. Each with its own authentication requirements, pagination patterns, and data shapes.

That surface doesn’t stay still. Endpoints are added, renamed, split behind gateways, or routed to new backing services. Documentation goes stale the moment teams ship new use cases, and those use cases often change request and response shapes in subtle ways — one payload adds nested filters, another returns a new envelope, a third changes how pagination tokens are emitted.

For a human developer, this is manageable. You open the documentation, search for what you need, try a few requests in Postman, read the response, iterate. The process is slow but navigable.

For a coding agent, this API surface is a wall.

Why Agents Struggle with APIs

This isn’t just about documentation format. There are structural reasons why traditional API tooling fails coding agents:

Why Traditional API Tools Fail Agents

The Core Insight: CLIs as Agent Interfaces

The answer was hiding in plain sight. CLIs are the original text-in, text-out interface. They’re composable, scriptable, and non-interactive by default. Every coding agent already knows how to run shell commands.

But most CLIs are designed for human ergonomics — colorful output, interactive prompts, confirmation dialogs. The insight wasn’t “build a CLI.” It was: build a CLI where the OpenAPI specification IS the interface.

This means:

• Zero hard-coded routes. Every endpoint comes from the spec. Add an endpoint to the spec, and it’s immediately available in the CLI. No code changes.
• The CLI is always complete. If the API has 1,000+ endpoints, the CLI has 1,000+ commands. No manual mapping, no forgotten endpoints, no drift between docs and reality.
• Discovery is built in. The same spec that defines endpoints also provides their schemas, parameters, and descriptions — all queryable from the terminal.

Design Decisions That Enable Agency

Every design choice was evaluated through a dual lens: does this work for a human developer at a terminal, AND does this work for a coding agent running commands non-interactively? Seven decisions stood out:

Design Decisions and Their Agent Impact

TTY Detection: The Dual-Mode Pattern

The most subtle design decision. When run in a terminal (TTY), the CLI offers an interactive fuzzy-search picker — type a few characters, see matching endpoints, select one. When run non-interactively (piped, backgrounded, or by an agent), it silently switches to structured output mode. No prompts, no confirmations, no color codes that break parsing.

The agent never needs to know about this. It just works.

Structured Output Envelope

In non-interactive mode, every response follows the same shape:

{"status": 200, "body": {"works": [...], "next_cursor": "abc"}, "headers": {...}}

Status codes, response bodies, and headers — all in a predictable envelope. The agent can write one parser that works for every endpoint. Contrast this with raw curl, where you’d need to parse status from headers, handle different content types, and deal with error formats that vary by endpoint.

Permission Boundaries

A regex-based allow/deny system controls which endpoints are visible and executable. Configuration lives in settings files — project-level or global — not in code. This means:

• Safe exploration: Give an agent access to read-only endpoints while blocking mutations
• Progressive trust: Start with a narrow allowlist, widen as confidence grows
• No code changes: Permissions are config, not logic

The Observability Surface for APIs

Before this tool, understanding the API landscape meant reading documentation pages one by one. After, the entire surface is queryable from the terminal.

Before vs. After: API Exploration Workflow

Patterns for Agent-Friendly CLI Design

The techniques that emerged from this project are generalizable. Any CLI that wants to serve both humans and coding agents can apply these patterns:

Agent-Friendly CLI Design Patterns

What Changes When Agents Can Explore

The most significant impact isn’t speed — it’s autonomy. When a coding agent can discover, understand, and invoke APIs without human guidance, the nature of the collaboration changes.

From “tell me the endpoint” to self-discovery

Without the CLI, a typical agent interaction looks like: “I need to list tickets. What’s the endpoint?” With it, the agent runs api domains, finds works, runs api list --domain works, finds /works.list, runs --dry-run to understand the schema, and executes. No human in the loop.

Integration workflows collapse

Building a feature that touches an unfamiliar API domain used to mean hours of documentation reading and Postman experimentation. Now the discovery-to-execution cycle is four commands. The agent handles the exploration; the developer focuses on the business logic.

The CLI is the documentation

New developers (and agents) don’t need to find and read API docs. The CLI itself is queryable documentation. api list is the endpoint catalog. --dry-run is the request reference. --fields is the response guide. The API is self-describing through its tooling.

Safe exploration in production

The permission model means agents can explore real environments without risk. Set up a read-only allowlist, point the agent at a staging environment, and let it learn the API surface. When ready, widen permissions for write operations. The progression from read-only exploration to full access is controlled, auditable, and reversible.

Using the CLI as an agent skill

The CLI compounds in value when wired into how Claude Code operates. A companion skill defines exactly when and how to use it, so Claude follows a documented workflow rather than inferring API mechanics from context.

CLAUDE.md as the entry point

CLAUDE.md is read at the start of every Claude Code session. A reference to the companion skill is enough to activate it:

## API access
When the task requires reading from or writing to any API endpoint, use the @cli-for-agents skill.

Claude treats this as a standing instruction. Any task involving API data triggers skill lookup before attempting direct execution.

What the skill defines

The skill is designed around the CLI’s own design principles: non-interactive first, incremental discovery, and fail usefully with correct examples. It teaches Claude three things:

When to use the CLI — any task that requires listing, filtering, reading, or writing API resources: “fetch open issues,” “create a work item,” “list accounts by domain.”

How to discover the right endpoint — the four-step pattern the CLI is built around, matching the terminal diagram above:

my-cli api domains                         # map the API surface
my-cli api list --domain <name>            # scope to a relevant domain
my-cli api <endpoint> --dry-run            # inspect before executing
my-cli api <endpoint> -F key=value --json  # execute with structured output

How to handle the response — the skill specifies the --json envelope shape (status, body, headers), instructs Claude to check status before processing body, and sets safe defaults: --dry-run for any write operation before executing, --fields to limit response size on large result sets, --paginate when completeness matters.

How Claude completes the task

With the skill active, “create a ticket for the login bug” becomes a four-step uninterrupted sequence. No human guidance needed for API mechanics:

my-cli api domains
# → finds 'works' domain

my-cli api list --domain works
# → finds /works.create — POST

my-cli api /works.create --dry-run
# → confirms required fields: title, type

my-cli api /works.create -F title="Fix login bug" -F type=issue --json
# → status: 201 — id: ISS-123

Claude discovers the surface, verifies the shape, and executes. The skill provides the method; the CLAUDE.md reference makes that method available at session start.

Takeaways

Each iteration of building this tool reinforced a set of principles about designing for the agent era: