cli-guide-spec — a guide command convention for agent-first CLIs

A tiny, copy-pasteable convention for giving any command-line tool a guide command that bakes the full operator/agent manual into the binary itself — the model, the loop, the concepts, the commands, the examples, and the gotchas — so an agent (or a human) can learn the tool end-to-end with one command and zero external docs.

It is deliberately small — one CLI subcommand, one JSON shape, optionally two HTTP routes — so an agent can add it to a new tool in a few minutes, and so tools written in different languages all expose the same discovery surface.

myapp guide                 # JSON by default — the full agent skill
myapp guide --human         # readable markdown reference
curl http://localhost:PORT/guide     # same skill over HTTP (if the tool runs a server)
curl http://localhost:PORT/llms.txt  # a short agent breadcrumb (the pointer to /guide)

Why

Agent-operated tools ship a binary, not a docs site. An agent that lands on a fresh machine with only the binary has no way to learn the tool's mental model — help lists commands, help-json lists flags, but neither teaches when to use what, what the loop looks like, or what the gotchas are. The .agents/ skills/ in the source tree are the real usage guides, but they never reach a customer who installed the binary via an install script.

This convention closes that gap: the guide is embedded in the binary (a //go:embed or an in-source constant), so it travels with every install. An agent reads it once and drives the tool with no external context. It is the single source of truth that help/help-json (the command catalog) cannot be.

The documents

File	For	What it is
PROTOCOL.md	implementers	the normative contract (MUST/SHOULD): the guide data shape, the CLI command, the HTTP endpoints, output formats, versioning
RECIPE.md	implementers	the 4-step how-to with reference snippets (Go + machin)
llms.txt	agents	the machine-first entry point — fetch this first
guide.schema.json	everyone	JSON Schema for the guide output body
SKILL.md	agents	drop-in skill: "add a guide command to this CLI"

The contract in one breath

• The CLI command is <tool> guide. It MUST output the guide as JSON by default (agent-first); --human SHOULD produce a readable markdown rendering of the same content. stdout = the guide; stderr = nothing or logs.
• The guide body is a JSON object with a stable, documented shape (see PROTOCOL.md §1): one_liner, model, loop, concepts, commands, examples, gotchas, see_also. Unknown fields MUST be ignored (forward compatibility).
• The guide is embedded in the binary — it MUST NOT fetch a URL at runtime. It travels with every install.
• A tool that runs an HTTP server SHOULD also serve GET /guide (the same JSON body) and GET /llms.txt (a short text breadcrumb that points at /guide and names the CLI command). /llms.txt is the agent's front door.
• Versioning: the guide SHOULD include the tool's version so an agent can detect staleness across updates.

Full details in PROTOCOL.md.

Reference implementations

These tools implement the convention across several languages and architectures — each is a worked example:

Tool	Language	Flavor	HTTP endpoints
remotecmd (rcmd)	Go	markdown reference	/guide + /llms.txt
chatsnip	machin	markdown reference	/guide
grepapi	machin	JSON agent-skill	/v1/guide
automaintainer (am / am-cloud)	Go	JSON agent-skill + --human markdown	/guide + /llms.txt (local daemon)

Relation to help / help-json

help and help-json are the command catalog — what commands and flags exist. guide is the mental model — what the tool is, how you use it end-to-end, and what bit you. They are complementary, not substitutes. A conforming tool SHOULD have both; guide's see_also SHOULD point at help-json.