agent-cli

--agent-help Convention

When building or modifying a CLI tool, always implement the --agent-help flag following this convention. This is not optional guidance -- it is the standard for making CLIs usable by LLM agents.

When to Use

• Building a new CLI tool in any language
• Adding or modifying help output for an existing CLI
• Designing command structure for a CLI application
• Adding subcommands, flags, or arguments to a CLI

When NOT to Use

• GUI applications or web APIs with no CLI component
• Simple one-shot scripts with no flags or subcommands

Why

--help is designed for humans: prose descriptions, grouped sections, multiple examples, flag aliases. Agents waste tokens parsing it and still get invocations wrong. --agent-help returns the minimum an agent needs to construct a correct call.

The Flag

Every CLI implementing this convention adds a single global flag: --agent-help

When called with no subcommand, returns tier 1 (index). When called with a command path, returns tier 2 (command detail).

Tier 1: Index

tool --agent-help returns a complete command index. Target: <300 tokens.

Format:

tool: one-line purpose
commands:
  cmd1 <required> [optional]  one-line
  cmd2 <required>  one-line
  group cmd3 --flag TYPE  one-line

Rules:

• One line per command, including inline required args
• Subcommands shown as group cmd not nested
• No flag details (tier 2)
• No aliases, no version, no author
• Sort by likely usage frequency if possible

Example:

ctx: persistent memory for LLM agents
commands:
  add --type TYPE --tag K:V... <text>  store a node
  query <search> [--type TYPE] [--limit N]  search nodes
  show <id>  display one node
  rm <id>  delete a node
  hook session-start [--project NAME]  session init
  hook session-end  session teardown
  init  create database
  version  print version

Tier 2: Command Detail

tool --agent-help <command> returns everything needed to invoke that one command. Target: <150 tokens.