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.

Format:

tool command <required-arg> [optional-arg] [flags]
flags:
  --name TYPE  purpose [default: X]
  --name TYPE  purpose [required]
  --name TYPE  purpose [conflicts: --other]
  --name TYPE  purpose [requires: --dep]
example:
  tool command --name value arg

Rules:

• TYPE is one of: string, int, bool, path, enum(a|b|c)
• Defaults only when non-obvious (omit [default: ""], [default: false])
• One example showing the common invocation
• Constraints inline: [required], [conflicts: --X], [requires: --X]
• No long descriptions, no flag aliases (-v/--verbose), no environment variable docs
• Positional args in signature with <required> and [optional]

Example:

ctx add <text> [flags]
flags:
  --type enum(decision|fact|pattern|observation)  node type [required]
  --tag string  key:value tag, repeatable
  --ttl string  auto-expire duration (e.g. 24h, 7d)
  --agent string  agent identity
example:
  ctx add --type fact --tag project:myapp --tag tier:pinned "the database uses postgres 15"

Tier 3: Error Hints

When a command fails, the error message should include enough for an agent to self-correct without another help call.

Format:

error: what went wrong
hint: correct usage or value constraint

Rules:

• error: states what was wrong with the input
• hint: shows the fix or valid values, NOT "run --help"
• For enum violations, list valid values
• For missing flags, show the flag with its type

Examples:

error: --type is required
hint: --type enum(decision|fact|pattern|observation)

error: unknown command "ad"
hint: did you mean "add"? commands: add, query, show, rm, hook, init, version

Bootstrap: The --help Breadcrumb

Agents that don't know about --agent-help will call --help first. Add one line at the bottom of your --help output so they discover it:

LLM agent? Use --agent-help for token-optimized usage.

This is the bridge. An agent sees it, switches to --agent-help, and gets the compact format from then on.

Implementation Guidance

Adapt the examples below to the user's target language and framework. The convention is language-agnostic -- if the user's framework isn't listed below, apply the same pattern: intercept a global --agent-help flag before dispatch, emit the compact format from the tier spec above.

$ARGUMENTS

Go (Cobra)

Add a persistent flag on root and a PersistentPreRun that intercepts it:

var agentHelp bool

func init() {
    rootCmd.PersistentFlags().BoolVar(&agentHelp, "agent-help", false, "Token-optimized help for LLM agents")
}

func agentHelpPreRun(cmd *cobra.Command, args []string) {
    if !agentHelp {
        return
    }
    if cmd == rootCmd {
        printAgentIndex()
    } else {
        printAgentCommand(cmd)
    }
    os.Exit(0)
}

For printAgentCommand, walk cmd.Flags() and emit the compact format. Don't reuse cobra's built-in help templates.

Python (Click)

@click.group()
@click.option('--agent-help', is_flag=True, hidden=True, help='Token-optimized help for LLM agents')
@click.pass_context
def cli(ctx, agent_help):
    if agent_help:
        if ctx.invoked_subcommand:
            print_agent_command(ctx.invoked_subcommand)
        else:
            print_agent_index()
        ctx.exit()

Rust (Clap)

#[derive(Parser)]
struct Cli {
    #[arg(long, global = true, hide = true)]
    agent_help: bool,
}

Intercept in main before dispatch. Walk Command::get_subcommands() and get_arguments() for the compact format.

Node (Commander)

program.option('--agent-help', 'Token-optimized help for LLM agents');
program.hook('preAction', (thisCommand) => {
  if (program.opts().agentHelp) {
    printAgentHelp(thisCommand);
    process.exit(0);
  }
});

Adding the --help Breadcrumb

Append to your help template/epilog:

• Cobra: rootCmd.SetHelpTemplate(cobra.CommandHelpTemplate + "\nLLM agent? Use --agent-help for token-optimized usage.\n")
• Click: @click.group(epilog="LLM agent? Use --agent-help for token-optimized usage.")
• Clap: #[command(after_help = "LLM agent? Use --agent-help for token-optimized usage.")]

Token Budget Reference

Worst case (unknown CLI, need one command): tier 1 + tier 2 = 2 calls, ~450 tokens. Best case (know the command): tier 2 = 1 call, ~150 tokens.