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