Man Files for Agent-Friendly CLIs: Why They Matter and How We Built Ours

3 min read Original article ↗

TL;DR

If your CLI stops at --help, agents will guess the rest. That creates bad command sequences, repeated retries, and avoidable failures for users.

That is the core problem.

When detailed docs are missing from the CLI itself, an agent can see command names but not the operational path. It may know docs init, docs push, and docs publish exist, but still fail to answer a simple user request like:

"Create documentation for this project and keep it updated."

Not because the CLI is weak, but because the guidance layer is too shallow.

Inspiration We Used

This implementation was directly inspired by two posts we studied:

The shared takeaway from both:

  • keep the interface simple
  • make docs queryable at runtime
  • avoid forcing agents to reconstruct workflows from terse help output

The Failure Mode We Wanted to Fix

Agents usually start here:

That’s correct behavior. But classic help output is built for quick human scanning, not multi-step machine execution.

Without deeper docs, agents tend to:

  1. Discover command names.
  2. Infer missing workflow details.
  3. Try likely flag combinations.
  4. Retry on failure until something works.

That loop burns time, tokens, and trust.

The fix is not “more text in --help.” The fix is a second layer: man-file style docs that are packaged with the CLI and queryable via commands.

The Pattern We Implemented

We kept it intentionally minimal.

1) --help stays concise

--help remains the discovery entrypoint, but now points to deeper docs.

2) Docs ship with the CLI package

We bundle static docs in man/ so they are:

  • offline-available
  • version-matched with the installed CLI
  • not dependent on API availability for first-use discovery

3) Runtime docs commands are basic and explicit

Only three core operations:

And a familiar alias:

That’s enough for most agent workflows.

Matching: How It Works Today

Current matching is keyword-weighted and deterministic.

For each topic, search scores matches in:

  • title
  • summary
  • topic path
  • body content

Weights are currently biased toward high-signal fields (title highest, then summary, then path/body).

Result ordering is stable:

  • first by score
  • then by path for ties

Why this matters:

  • agents get repeatable results
  • two runs with the same query return the same ordering
  • behavior is easy to reason about and debug

This is intentionally simple for MVP reliability.

Why This Matters More Than It Sounds

This is not just a docs nicety.

For agent adoption, this is infrastructure.

If the CLI cannot teach an agent how to use itself in a deterministic way, users will see:

  • inconsistent execution quality
  • false negatives (“command not supported” when it is)
  • fragile automation

A strong man-file layer closes that gap.

Keep It Boring, Keep It Reliable

The highest-leverage move here is not complexity. It’s clean separation:

  • --help for quick discovery
  • cli-docs/man for workflow depth
  • stable output for machine consumption

That combination makes agents less improvisational and more correct.

And when users ask for something basic like “create and maintain docs for this project,” the CLI can actually guide the agent end-to-end.

If you want to see the current Docsalot CLI docs in action, start here: https://docs.docsalot.dev/cli.