Agent DX Guide for CLI Projects

A pattern language for designing command-line tools that agents can use effectively.

Core Principles

Minimal Ceremony

One command for the common case.

Bad:

mytool init --config ./config.yaml
mytool create entry --type log
mytool entry set-field --field title --value "Fixed bug"
mytool entry commit

Good:

mytool log "Fixed bug" --body "Details..."

Guidelines:

• Collapse multi-step workflows into single commands
• Use positional arguments for the most common parameter
• Provide sensible defaults for everything else
• Reserve subcommand trees for genuinely distinct operations

Clear Next Action

Tell agents what to do next.

Bad:

$ mytool status
Repository initialized.
3 items tracked.

Good:

$ mytool status
Repository initialized.
3 items tracked.

Run: mytool pending    # See what needs attention
Run: mytool process    # Handle pending items

Patterns:

• pending / ready commands that surface work
• Include suggested next commands in output
• JSON output includes next_action or suggested_commands fields

Context Injection

Provide a prime command that outputs workflow state for session bootstrapping.

$ mytool prime
MyTool workflow context
=======================
Repo: my-project
Branch: main

Pending: 5 items need attention

Quick commands:
  mytool pending     # See pending items
  mytool show --last # View last action

Why this matters:

• Agents lose context on session boundaries
• /clear and compaction wipe working memory
• prime restores workflow state in one call

JSON Everywhere

Every command supports --json for structured output.

{
  "status": "created",
  "id": "tb_2026-01-15_abc123",
  "anchor": "abc1234def5678...",
  "commits": 3
}

Guidelines:

• --json flag on every command, no exceptions
• Errors also return JSON: {"error": "message", "code": 1}
• Include machine-readable fields (full SHAs, IDs, counts)

Sensible Defaults

Commands work without flags for the common case.

mytool log "Message"
# Anchor defaults to HEAD
# Range defaults to since-last-entry
# Format defaults to human-readable

• Defaults should match 80% of use cases
• Never require configuration before first use

Token Efficiency

Batch Operations

Instead of:

mytool process item1
mytool process item2
mytool process item3
# 3 tool calls, 3 permission prompts

Provide:

mytool process --batch
# 1 tool call, processes all pending

Patterns:

• --batch flag for processing multiple items
• Accept multiple positional arguments
• Batch JSON input via stdin

Compact Output Modes

mytool query --last 5 --oneline   # Compact for scanning
mytool query --last 5 --ids-only  # IDs only for scripting

Allowlist-Friendly Commands

Design commands that can be pre-approved:

• Prefer declarative over imperative commands
• Avoid eval/exec patterns
• Make destructive operations explicit: mytool delete --confirm
• Support --dry-run for write operations

Error Handling

Structured Errors

{
  "error": "Missing required flag: --why",
  "code": 1,
  "hint": "Use --minor for trivial changes"
}

Exit Codes

Recoverable Failures

Bad:

Error: Entry already exists.

Good:

Error: Entry already exists for anchor abc1234.
Use --replace to overwrite, or --anchor <sha> to target another commit.

Self-Documentation

Help Text

$ mytool --help
A development ledger for capturing what/why/how.

Core Commands:
  log       Record work with what/why/how
  pending   Show items needing attention
  prime     Output workflow context

All commands support --json for structured output.

Skill Generation

Provide a command that outputs content for agent skills:

mytool skill
mytool skill --format json

Agent Execution Contract

Include in CLI documentation:

1. Use CLI, not internals - Call commands, consume JSON output
2. Trust the tool - Don't parse config files directly
3. Use --dry-run - Validate before writing
4. Check pending - Know what needs attention before starting
5. Prime on session start - Restore context after /clear

Integration Patterns

Provide workflow snippets for CLAUDE.md:

## Workflow

At session start:
  mytool prime

After completing work:
  mytool log "what" --why "why" --how "how"

At session end:
  mytool pending    # Check for undocumented work

Anti-Patterns to Avoid

Checklist

See references/checklist.md for the full design checklist.