CLIs for agents

The dedicated thesis: the CLI is the native interface between agents and software — text in, text out, composable, scriptable, no DOM to scrape. “Agents love CLIs” stopped being a vibe when Cloudflare measured it: agent share of their wrangler usage hit 48% within a year, with agents running ~2× the distinct commands and 4× the command diversity of humans (clippings/blog-cloudflare-com-cloudflare-cf-cli-launch.md). The sibling notes: CLI all the things (the human-pleasure side), Agent-accessible product (the full product discipline — this note is its CLI-shaped chapter).

Why the CLI wins for agents

• Pipes are the agent API: stdin/stdout compose without adapters; jq turns any JSON-emitting command into a queryable data source. A browser is a rendering engine with a human-shaped lock; a CLI is a function call with a man page.
• One interface, two users: the same binary serves a human in a terminal and an agent in a loop — no separate automation API to build, document, and drift.
• Agents don’t need the chrome: no sensory accommodations (Bailey’s divergence list) — only structure, consistency, and recoverability.

The design rules (distilled from the captures)

1. JSON is the default interface — “pretty printed for humans and condensed for agents for maximum context savings” (cf). The anti-pattern: unicode tables an agent must squint at; the anti-anti-pattern: --json flags that exist on some commands. Make JSON the contract, not an option.
2. Generate the CLI from the schema — Cloudflare’s Forge builds cf’s 3,000+ commands directly from the OpenAPI schemas behind their docs/SDKs: consistency at scale, the entire API surface covered, verbs can’t drift per team. The schema is the CLI.
3. Arg-driven cores that ask nothing — lifehacker’s terminal-frontend split (clippings/lifehacker-dev-hacks-terminal-frontend-architecture.md): “the core never knows whether a human or a cron job filled in its arguments.” All interactivity lives in disposable frontends (gum menus, TUIs); the core takes arguments, validates, exits with codes. See Do-nothing scripting’s arc.
4. Idempotency + structured errors — agents retry autonomously, so operations must be safe to repeat (idempotency keys where creation isn’t inherently idempotent), and errors must say whether/when/what-to-change in machine-readable form (Agent-accessible product).
5. Discoverability at scale — when 3,000 commands exist, search and steering replace tab-completion memorization (cf’s bespoke command search); for smaller tools: good --help, stable verbs, examples in the README.
6. Write the docs for agents too — basal’s author structures his README so “agents (codex, claude code) poradzą sobie na tym tekście świetnie”; a long, well-organized README is agent documentation (contextmaxxing at repo level).

The vault’s own instances

• ocli — the user’s own lane: Typer+Rich CLI/TUI with connect() lib; column registries and JSON output are the agent-facing contract
• agent-slack (OSS) (547★, MIT, TS/Bun) — Slack automation CLI purpose-built for agents: compact JSON with empty/null fields pruned (token efficiency as the first design principle), zero-config auth via the Slack Desktop app’s session, human-in-the-loop message compose (browser editor) suppressed in CI, canvases as Markdown, artifacts auto-downloaded to local paths
• Agent Reach (OSS/Agent-Reach (OSS).md) — a CLI whose entire product is other sites’ data, health-checked: the read-side of the agent web
• kubectl — the canonical proof via Tuist: “LLMs speak the language of Kubernetes” — a good CLI makes even cluster orchestration agent-drivable
• cf / wrangler — the reference implementation (see Agent-accessible product case study)
• hermes CLI — hermes config set, hermes profile install: this note’s rules applied to an agent platform itself

The one-liner: a CLI that emits clean JSON, takes explicit args, fails with structure, and repeats safely is an SDK you didn’t have to write.

Related: CLI all the things · Agent-accessible product · Do-nothing scripting (arg-driven cores) · Agent skills (skills wrap these CLIs) · tuist (OSS) (agents-speak-the-language thesis)

Discoverability of installed tools: flaviocopes’ CLI Tools

CLI Tools (flaviocopes, free/OSS macOS app + companion CLI; via @flaviocopes — “built an app to help me remember which CLI tools I already have, turns out it can be useful for agents, too”) — a catalog of every command-line tool on the machine: scans Homebrew/npm/Cargo + trusted bins (~/.local/bin, ~/.bun/bin, ~/.deno/bin), groups package commands as one entry, attaches tldr pages, --help-extracted examples, and your own shell history per tool (“the command I already typed once is usually the best example of how I use it” — history read from zsh/bash/fish, kept in memory, never written to the catalog). The agent-facing move: clitools list --json / inspect / history — “a coding agent working on my machine can ask which tools are installed and how to call them, instead of guessing or installing something I already have.” That closes a real gap this note’s rules assume away: discoverability at scale isn’t just search across all possible commands (cf) — it’s an inventory of what THIS machine already has, with usage-grounded examples. The Linux-portable recipe: package-manager scans + tldr + shell-history grouping + one JSON surface — a weekend script, and a natural hermes skill or ocli subcommand. Sibling app Skillscout does the same for agent skills (the same inventory problem, one layer up).

The data tier: Leviathan (search a database without reading it)

leviathan (OSS) (Rust, single static binary; via @joshuagunnn — “agents are great at reasoning over five records and terrible at finding them in a million”) — an indexer that lets agents search any-size data without loading it: point at JSONL/CSV/SQLite or pipe Postgres/MySQL/DuckDB/Mongo; infers schema, builds a full-text index, returns short cited result cards (~450 tokens per answer at 10K or 1M rows alike; at 1M records: 99% of questions get a relevant record in top-5, 33 ms median, worst case 602 tokens vs grep’s 9.7M). Honest sizing: “under ~100K rows grep is honestly fine. This is for when your data outgrows the context window.” Distribution stance echoes this note’s rule 2 debate: CLI-first, MCP optional — “MCP schemas tax every session whether you use them or not; a skill file costs zero tokens until it’s called.” Fits the emerging agent-data stack: qmd here, Leviathan for record-shaped data, dnsglobe (OSS)-style TUIs for humans — retrieval moving out of context and into indexed surfaces the agent queries by citation.

Agent-to-agent relay: Agent Tincan (the attack of the personal agents)

mvanhorn’s October edition of “every agentic engineering hack I know” (X article 2106810118751051777, quoted in full in the captured thread; tweet) — headline thesis: “the biggest change since June isn’t in the terminal. It’s the attack of the personal agents.” Claude Code stays the brain (Opus 5.5 in cmux), but the new layer is Agent Tincan — a small relay on your Tailscale network: every agent dials out to it, one agent asks another for help, the relay wakes the other agent the way it wakes best, and carries the answer back. Your laptop can be off. Use-cases from the field: Muse→fo handoff when a karaoke bar hung up on AI (fo put a human on the call, booked — “I didn’t even read the prompt”); Instinct↔fo pairing for email triage; images from ChatGPT on demand. The agent-interviews-you pattern is the quiet flex: the article itself was written by Claude Code drafting 12 questions → fo calling his cell five times on a Sunday while he pushed a stroller (“every time I said ‘I have to take my kid to the bathroom, call me back in two minutes’ it just did”) → transcript back → article. “I did not type a word.” Other keepers: personal-agent league table (Instinct #1 at “48.5/50 on my IQ test”, Grok Bot #2 running the family’s Canadian citizenship application over its own AgentMail inbox — “treats the rest of us like its agents”), GOG CLI for Google Sheets/Docs (“better than any connector”), Headroom for subscription-limit metering, /ce-plan → /ce-work Compound Engineering reflex, “turn every frustration into a skill.” Vault fit: Tincan is the mesh answer to what CLIs for agents catalogs as point solutions — no MCP broker, just a relay on your own tailnet; kin to Agent-accessible product’s agent-to-agent reachability and the ACP sessions in Agent Client Protocol.

chat.hf.co: LLM chat over SSH, zero setup (2026-10-08)

XciD_ (21❤; video demo captured): ssh chat.hf.co — “no config. no key. nothing. chat with open models, zero setup.” Hugging Face ships an LLM chat where the entire client is an SSH connection: first-party auth by connection, TUI rendered server-side over the terminal channel. For this note’s thesis it’s the purest specimen yet of zero-friction CLI distribution — no install, no API key ceremony, the SSH handshake is the onboarding. USER ASSOCIATION, verbatim: “Reminds me charmbracelet wish and terminal coffee” — the charmbracelet/wish lane (SSH apps as first-class Go apps; wish = SSH server framework behind many terminal-hosted apps, e.g. terminal.coffee-style chat) and terminal coffee (the SSH-chat genre): the kinship is exact — wish proved any TUI can live behind ssh host, and HF applied it to the biggest zero-setup payload there is, open-model chat.

David Fowler: CLIs as exploration harnesses (2026-10-11)

@davidfowl (48❤/3k views, captured) — .NET’s platform architect on the pattern’s next step: CLIs for agents aren’t just for operating systems, they’re for exploring and breaking them:

“My latest pastime is building CLIs that make it easier for agents to explore systems. I don’t mean writing deterministic end-to-end tests (those come later). I mean giving agents a headless way to exercise common system interactions. Once you have that, ask the agent to explore all the ways things can go wrong. It gets real feedback from running the system, not just reading the code.”

The full loop he ties together — code access + a harness to quickly verify changes + telemetry — “now the agent can find a bug, fix it, and verify the fix on its own. And it can get there through combinations of interactions you never thought to test.” Origin: distributed systems — he plugs Aspire (the .NET local-orchestration/observability stack, where the pattern was discovered).

Why this matters for the thesis: it moves agent CLIs from the command lane (call a function, get JSON — the note’s rules 1-6) to the investigation lane — the CLI as a fuzzable interface to a live system, feedback loop included. That’s the same move explain-then-fix makes at skill level and the copyconstruct agentic-debugging piece makes methodologically (“prove the change on the surface a person uses”): explore-by-running beats read-the-code. Also the strongest instance yet of the note’s test kinship — the CLI becomes the agent’s hands for Agent tests’ “verifiable artifact at the end,” with telemetry as the observation channel.