cli-tools-for-agents

Design a purpose-built project CLI as the primary tool surface for AI coding agents, instead of in-process tool or MCP servers. Covers text-by- default output with opt-in --json (format follows the consumer), the exit- code taxonomy, structured errors, file-based payloads with a validate verb, preflight verbs for gated transitions with findings named by the transition they block, job-shaped long operations, identity resolution, a doctor self-check, and build-parity stamps. Use when building a CLI for agents, migrating away from in-process tool servers, designing tool output and error contracts, deciding between text and JSON output for an agent- facing tool, designing a lint or check command that runs ahead of a gate, choosing severity levels for findings, or deciding how agents should invoke project actions.