AI & MCP

Introducing CLI generation: the agent interface your API is missing

Nolan Sullivan

March 23, 2026 - 5 min read

---

Every API team ships docs. Most ship SDKs. Some ship MCP servers. Not enough ship a CLI, and in a world of AI agents, that’s a problem. CLIs are the interface agents currently know how to use best.

Today we’re launching CLI generation in beta. Speakeasy will turn any API into a fully functional CLI written in Go, complete with an interactive TUI for humans and a machine-readable output mode designed for AI agents. One generation, both audiences served.

Why CLIs matter in the age of agents

MCP servers have been a breakthrough for connecting AI to APIs. We generate those too, and we believe in them. But MCP serves a different audience: non-technical users operating in a shell-less execution environment. Whereas CLIs shine in local development environments. For coding agents like Claude Code, Cursor, Codex, and Windsurf, a CLI is often the most natural tool for them to reach for.

What makes them so performant?

• Progressive disclosure. Subcommands and --help at every level let agents explore incrementally, without loading hundreds of tool definitions upfront.
• LLM familiarity. Models trained on billions of shell scripts already understand CLI conventions. For well-structured CLIs, agents often don’t need to read help text at all.
• Composability. Agents can chain CLI commands with Unix pipes, filtering output with jq and stripping irrelevant data before it enters context. That saves tokens and keeps agent reasoning focused.

Agent mode: built in

cloudvault files get config.yaml --bucket production
 
bucket: production
file: config.yaml
metadata:
  size: 2048
  lastModified: 2026-03-25T14:32:01Z
  contentType: application/x-yaml
  etag: a3f8c91b
config:
  app:
    name: CloudVault API
    version: 3.2.1
    environment: production
  database:
    host: db-prod-primary.internal
    port: 5432
    name: cloudvault_prod
    pool:
      min: 10
      max: 50
  services[3]{name,url,timeout,retries,enabled}:
    auth,https://auth.internal:8443,5000,3,true
    billing,https://billing.internal:8080,10000,5,true
    notifications,https://notify.internal:9090,3000,2,false

Speakeasy-generated CLIs automatically detect when they’re running inside an agent environment. When Claude Code, Cursor, Codex, etc. call your CLI, the CLI switches to agent-mode:

• TOON output format. A structured, machine-readable format that agents can parse reliably — no screen-scraping terminal escape codes.
• Disabled interactivity. No prompts, no TUI, no blocking on user input. Just clean input/output.
• Structured error codes. Agents can programmatically handle failures without parsing error messages.

Agents can also explicitly enable this with the --agent-mode flag, or request specific output formats like JSON, YAML, or table.

Beyond output, generated CLIs expose their capabilities through multiple discovery mechanisms. An llms.txt file enables LLM-based discovery, while skills.md integrates with agent skill registries. JSON Schema definitions for all commands and responses give agents full type safety when validating inputs and parsing outputs.

What you get out of the box

cloudvault explore
 
┌──────────────────────────────────────────────────────────────────────┐
│ CloudVault: Manage your cloud storage.                               │
├──────────────────────┬───────────────────────────────────────────────┤
│   auth/              │  upload                                       │
│   files/             │  Upload a file to the specified bucket        │
│   create-bucket      │                                               │
│   delete-bucket      │  Example:                                     │
│   get-user           │    cloudvault upload --bucket prod            │
│   list-objects       │      --file ./data.csv                        │
│ > upload             │                                               │
│                      │  Required Flags:                              │
│                      │    --bucket  string  Target bucket [required] │
│                      │    --file    string  Local file path          │
│                      │                                               │
│                      │  Optional Flags:                              │
│                      │    --key           string  Custom object key  │
│                      │    --content-type  string  MIME type override │
├──────────────────────┴───────────────────────────────────────────────┤
│ root                                        ↑↓ · enter · esc · / · q │
└──────────────────────────────────────────────────────────────────────┘

Every generated CLI ships with production-grade features from day one:

Interactive TUI. An explore command lets users browse all available operations, view documentation, and execute commands — without memorizing syntax. When a required parameter is missing, the CLI prompts for it interactively.

Flexible input. Commands accept input through individual flags, a --body JSON argument, or stdin. Byte fields accept file paths, base64, or raw strings. The priority ordering is predictable: flags override body, body overrides stdin.

Smart output. Five output formats — pretty, json, yaml, table, and toon — cover every use case from human browsing to agent automation. Built-in --jq support lets users and agents filter JSON output inline.

Authentication. OAuth 2.0, API keys, bearer tokens, and custom schemes all work out of the box. Secrets are stored in the OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service) with a config file fallback.

Pagination and retries. List commands handle pagination automatically. Failed requests retry with exponential backoff. Both are configurable via flags.

Dry run and debug. The --dry-run flag previews requests without sending them. The --debug flag outputs full request/response diagnostics to stderr, keeping stdout clean for piping.

From spec to CLI in minutes

Getting started takes three inputs: a package name, a CLI name, and an environment variable prefix. Speakeasy analyzes the OpenAPI spec — endpoints, parameters, response types — and generates a complete, buildable Go project.

speakeasy run cli \
  --schema openapi.yaml \
  --out ./cloudvault-cli

The generated project includes:

• CLI commands mapped to every API operation, grouped by tags with intelligent stutter removal (so users list-users becomes users list)
• A wrapped Go SDK handling authentication, pagination, retries, and error handling
• Shell completion for bash, zsh, fish, and PowerShell
• GoReleaser configuration for cross-platform builds
• Installation scripts for Linux, macOS, and Windows

When the API changes, regenerate the CLI to keep commands, flags, and documentation in sync. New endpoints become new commands. Updated parameters become updated flags. The CLI and the API never drift apart.

Customize and extend

cli:
  cliName: "cloudvault"
  envVarPrefix: "CLOUDVAULT"
  removeStutter: true
  interactiveMode: true
  interactiveAuth: true
  generateRelease: true
  enableCustomCodeRegions: true

Generation is the starting point, not the ceiling. The gen.yaml configuration controls everything from the executable name and environment variable prefix to interactive theming with custom colors.

Custom code regions let teams add hand-written commands on top of the generated base. Add business logic, domain-specific workflows, or convenience aliases — and those additions survive regeneration.

CLIs and MCP: better together

This isn’t a CLI-versus-MCP story. The best platforms will ship both, because they serve different audiences and runtimes. Speakeasy generates both from one source of truth — two interfaces, every audience covered.

Get access

CLI generation is in beta and we’re working closely with early users to refine the experience. If you’re an API team looking to ship an agent-ready CLI, reach out to us to get started.

Explore the documentation to see the full technical details, or check out the product page for a closer look at what generated CLIs can do.