Agent-Friendly CLI Design

Checklist and patterns for building CLIs that agents can use effectively. Most CLIs assume a human at the keyboard — these patterns close the gap.

Core Principles

1. Non-Interactive by Default

Every input must be passable as a flag. Interactive prompts block agents.

# ❌ Blocks agents
$ mycli deploy
? Which environment? (use arrow keys)

# ✅ Works
$ mycli deploy --env staging

Keep interactive mode as fallback when flags are missing, never the primary path.

2. Progressive Help Discovery

Don't dump all docs upfront. Let agents discover via --help per subcommand.

# Agent runs top-level, sees subcommands
$ mycli --help

# Picks one, gets specific help
$ mycli deploy --help

An agent wastes no context on commands it won't use.

3. Useful --help with Examples

Every subcommand gets --help. Every --help includes examples. Agents pattern-match off examples faster than descriptions.

$ 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

4. Flags and stdin for Everything

Agents think in pipelines. Support chaining and piping.

cat config.json | mycli config import --stdin
mycli deploy --env staging --tag $(mycli build --output tag-only)

Don't require positional args in weird orders. Don't fall back to interactive prompts for missing values.

5. Fail Fast with Actionable Errors

Missing flag? Error immediately with correct invocation. Don't hang or print vague messages.

# ❌ Bad
$ mycli deploy
Error: missing required arguments

# ✅ Good
$ mycli deploy
Error: --env is required
Usage: mycli deploy --env \x3Cstaging|production> [--tag \x3Cversion>]

Agents self-correct when given something to work with.

6. Idempotent Commands

Agents retry constantly — network timeouts, context loss mid-task. Running the same command twice should be safe.

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

$ mycli deploy --env staging --tag v1.2.3
✓ Already deployed, no-op

7. --dry-run for Destructive Actions

Let agents preview before committing.

$ 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.

8. --yes / --force to Skip Confirmations

Humans get "are you sure?" — agents pass --yes.

$ mycli delete-all --yes

Make the safe path the default but allow bypassing.

9. Predictable Command Structure

Pick a pattern and use it everywhere. If an agent learns one, it can guess the rest.

# resource + verb pattern
mycli service list
mycli deploy list
mycli config list

10. Structured Output on Success

Return actionable data, not just decorative messages.

# ❌ Cute but unhelpful
$ mycli deploy
🚀 Deployed successfully!

# ✅ Actionable
$ mycli deploy --env staging --tag v1.2.3
deployed v1.2.3 to staging
url: https://staging.myapp.com
deploy_id: dep_abc123
duration: 34s

Support --json for machine-readable output when possible.

11. Consistent Exit Codes

• 0 = success
• 1 = general error
• 2 = usage error (bad args)

Agents use exit codes to decide next steps.

Audit Checklist

When reviewing an existing CLI for agent compatibility, check each item:

When Designing a New CLI

1. Start with the flag-only interface. Add interactive prompts later as convenience.
2. Write the --help examples before writing the implementation.
3. Default to --json output internally, add human-friendly formatting on top.
4. Every write operation gets --dry-run. No exceptions.
5. Test by having an agent use it. Watch where it gets stuck.

Source

Based on Eric Zakariasson's (Cursor) "Building CLIs for agents" (March 2026), field-tested across ClawVault, WorkGraph, and Versatly CLI ecosystem.