pproenca/dot-skills/cli-for-agents

Agent-Friendly CLI Design Best Practices

Prescriptive design and review standards for Command-Line Interface Design targeting AI agents and scripts, not just humans typing at a prompt. Human-oriented CLIs often block agents: interactive prompts, huge upfront docs, help text without copy-pasteable examples, error messages without fixes, no dry-run mode. This skill prioritizes rules by blast radius — from "the agent cannot use this CLI at all" (CRITICAL) to "the agent has to read help one extra time" (MEDIUM).

Use this skill both when building a new CLI and when reviewing an existing one for agent-friendliness.

This skill contains 45 rules across 8 categories.

When to Apply

Reference these guidelines when:

• Writing --help text for any subcommand
• Designing new flags, arguments, or subcommands
• Crafting error messages or exit codes
• Adding destructive operations that need dry-run or confirmation
• Choosing between interactive prompts and flag-only inputs
• Shaping success output so agents can chain commands
• Reviewing an existing CLI for headless-usability regressions

Rule Categories by Priority

Note: help-examples-in-help is rated CRITICAL within the HIGH help- category because its specific failure — help text without examples — makes every other help rule moot. The category label reflects the average, not the worst case.

Quick Reference

1. Non-interactive Operation (CRITICAL)

• `interact-flags-first` — Express every input as a flag first; prompts are TTY-only fallback
• `interact-detect-tty` — Check isatty() before prompting
• `interact-no-arrow-menus` — Replace arrow-key menus with flag-selected choices
• `interact-no-input-flag` — Support --no-input to force non-interactive mode
• `interact-no-timed-prompts` — Never use timed prompts or press-any-key screens
• `interact-no-hang-on-stdin` — Don't block on stdin when a TTY is attached

2. Help Text Design (HIGH)

• `help-examples-in-help` — Include copy-pasteable examples in every --help
• `help-per-subcommand` — Every subcommand owns its own --help
• `help-no-flag-required` — Show help when invoked with zero arguments
• `help-layered-discovery` — Top-level help is a navigational index
• `help-flag-summary` — List both short and long forms for every flag
• `help-suggest-next-steps` — Suggest what to run next in help and success output

3. Error Messages (HIGH)

• `err-exit-fast-on-missing-required` — Exit fast on missing required flags
• `err-actionable-fix` — Include a concrete fix in every error message
• `err-stderr-not-stdout` — Send errors to stderr, not stdout
• `err-non-zero-exit-codes` — Use distinct non-zero exit codes for distinct failures
• `err-include-example-invocation` — Include a correct example invocation in errors
• `err-no-stack-traces-by-default` — Reserve stack traces for --debug mode

4. Destructive Action Safety (HIGH)

• `safe-dry-run-flag` — Provide --dry-run for every destructive command
• `safe-force-bypass-flag` — Provide --yes / --force to skip confirmations
• `safe-confirm-by-typing-name` — Require typing the resource name for irreversible actions
• `safe-no-prompts-with-no-input` — Never prompt when --no-input is set
• `safe-idempotent-cleanup` — Exit successfully when delete targets are already gone
• `safe-crash-only-recovery` — Design multi-step commands for crash-only recovery

5. Input Handling (HIGH)

• `input-accept-stdin-dash` — Accept - as filename for stdin and stdout
• `input-flags-over-positional` — Prefer named flags over positional arguments
• `input-stdin-for-secrets` — Accept secrets through stdin or file, never as flag values
• `input-env-var-fallback` — Accept common flags through environment variables
• `input-no-prompt-fallback` — Never fall back to a prompt when a flag is missing

6. Output Format (MEDIUM-HIGH)

• `output-json-flag` — Provide --json for stable machine-readable output
• `output-ndjson-streaming` — Stream large result sets as NDJSON
• `output-bounded-by-default` — Bound default output size with --limit and --all
• `output-machine-ids-on-success` — Return chainable values on success, not just "Done"
• `output-respect-no-color` — Disable ANSI color when NO_COLOR or non-TTY
• `output-no-decorative-only` — Avoid relying on decorative output to convey state
• `output-one-record-per-line` — One record per line for grep-able human output

7. Idempotency & Retries (MEDIUM-HIGH)

• `idem-retry-safe` — Make running the same command twice safe
• `idem-create-or-skip` — Make create commands skip when target already exists
• `idem-stable-output-on-skip` — Return the same output shape whether acting or skipping
• `idem-state-reconciliation` — Prefer "ensure state" semantics over delta application
• `idem-stable-identifiers` — Accept user-provided names instead of auto-generating IDs

8. Command Structure (MEDIUM)

• `struct-resource-verb` — Use a consistent resource-verb command shape
• `struct-flag-order-independent` — Parse flags in any position relative to subcommands
• `struct-no-hidden-subcommand-catchall` — Avoid catch-all handlers for unknown subcommands
• `struct-standard-flag-names` — Use standard flag names (--help, --version, --verbose, --quiet)

How to Use

When building a new CLI

Start at CRITICAL and walk down. The first two categories (interact- and help-) are non-negotiable — if any rule in these is violated, the CLI is unusable by agents regardless of how good the rest is. After those, work through err-, safe-, and input- — these are where most real-world friction lives. output-, idem-, and struct- are polish that compounds across many invocations.

When reviewing an existing CLI

Run through this checklist in priority order:

1. Non-interactive path — invoke every subcommand with --no-input or under </dev/null and see which hang
2. Layered help — does mycli --help list subcommands only, or dump everything?
3. Examples on `--help` — every subcommand's help should end with a runnable Examples section
4. Error messages with invocations — does every error tell the caller exactly which flag to add?
5. stdin/pipeline story — can you pipe output into input? Does - mean stdin?
6. Exit codes — are usage errors (2), runtime failures (1), and transient failures (69) distinct?
7. Dry-run — every destructive command has --dry-run (or equivalent)
8. Confirmation bypass — every destructive command has --yes/--force
9. Consistent command structure — do service list, deploy list, config list all exist and work the same way?
10. Structured success output — does deploy return a deploy_id the agent can use next?

Individual rules

Read individual reference files for detailed explanations and code examples:

• Section definitions — Category structure and impact levels
• Rule template — Template for adding new rules

Reference Files