Building Agent-Proof CLIs

agentsclidevopslink-note

Agents stumble over CLIs designed for humans: they freeze at interactive prompts or drown in verbose help text without examples. Here's how to craft CLIs that agents devour smoothly.

Ditch Interactive Prompts

Agents can't mash arrow keys or guess "y/n." Force every input via flags. Reserve interactive mode for incomplete flags.

# Agent killer
$ mycli deploy
? Which environment? (use arrow keys)

# Agent delight
$ mycli deploy --env staging

📝 Craft note: Short, punchy sentences ("Agents can't mash arrow keys") mix with a code block for visual impact. This creates sentence variety: staccato rhythm grabs attention, then code shows the contrast. Original buried the point in explanation.

Hide Docs Until Needed

Agents probe subcommands on demand: mycli deploy --help. Skip dumping the full manual. Discovery beats overload.

Supercharge --help with Examples

Agents pattern-match examples faster than prose. Every --help needs options and copy-pasteable snippets.

$ mycli deploy --help
Options:
  --env     Target environment (staging, production)
  --tag     Image tag (default: latest)
  --force   Skip confirmation

Examples:
  mycli deploy --env staging
  mycli deploy --env production --tag v1.2.3
  mycli deploy --env staging --force

📝 Craft note: Parallel structure in the examples list ("mycli deploy --env X", repeated) mirrors CLI rhythm, making it scannable and memorable. Original listed options flatly; this echoes agent parsing logic.

Embrace Flags and Stdin Pipelines

Agents chain tools like cat config.json | mycli config import --stdin. Ditch positional args or prompt fallbacks. Let pipes flow.

mycli deploy --env staging --tag $(mycli build --output tag-only)

Fail Fast, Suggest Fixes

Missing flag? Spit an error with the exact fix. Agents self-correct from clear cues.

Error: No image tag specified.
  mycli deploy --env staging --tag <image-tag>
  Available tags: mycli build list --output tags

📝 Craft note: Precise nouns ("cues" over "something to work with") and strong verbs ("Spit an error" vs. "Error immediately") sharpen the directive. Shows urgency without filler like "don't hang."

Go Idempotent

Agents retry amid timeouts. Duplicates waste cycles. Same deploy twice? Output "no-op."

Add --dry-run Previews

For deletes or deploys, preview first. Agents validate, then commit.

$ mycli deploy --env production --tag v1.2.3 --dry-run
Would deploy v1.2.3 to production
  - Stop 3 running instances
  - Pull image registry.io/app:v1.2.3
  - Start 3 new instances
No changes made.

$ mycli deploy --env production --tag v1.2.3
✓ Deployed v1.2.3 to production

📝 Craft note: Bullet list with parallel structure ("Stop X", "Pull Y", "Start Z") builds rhythm and clarity in the dry-run output. Transitions smoothly to success via contrasting code blocks, guiding the eye.

Bypass with --yes/--force

Default to safe confirmations for humans. Agents slip --yes to skip.

Stick to Predictable Patterns

mycli service list predicts mycli deploy list. Resource + verb everywhere.

Output Structured Success Data

Skip emojis. Deliver deploy ID, URL, duration—machine-readable gold.

deployed v1.2.3 to staging
url: https://staging.myapp.com
deploy_id: dep_abc123
duration: 34s

These tweaks slash agent debugging. Humans intuit; agents demand explicit. What patterns have you added? Share below!

📝 Craft note: Opening hook ("Agents stumble over CLIs designed for humans") shows the pain vividly instead of telling "you've seen it get stuck." Specific imagery hooks readers immediately, unlike the original's generic start.

← All notes