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.

bash

# ❌ 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.

bash

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

text

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

bash

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.

bash

# ❌ Bad
$ mycli deploy
Error: missing required arguments

# ✅ Good
$ mycli deploy
Error: --env is required
Usage: mycli deploy --env <staging|production> [--tag <version>]

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.

bash

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

bash

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

bash

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

bash

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

10. Structured Output on Success#

Return actionable data, not just decorative messages.

bash

# ❌ 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:

#PatternCheck1Non-interactiveCan every input be passed as a flag?2Progressive helpDoes each subcommand have its own --help?3Examples in helpDoes --help include usage examples?4Stdin supportCan data be piped in via --stdin or -?5Fast failuresDo missing args error immediately with usage hint?6IdempotencyIs running the same command twice safe?7Dry runDo destructive commands support --dry-run?8Skip promptsIs there --yes / --force for confirmations?9Predictable structureIs command naming consistent (resource + verb)?10Structured outputDoes success output include actionable data?11JSON outputIs --json available for machine parsing?12Exit codesAre exit codes consistent (0/1/2)?

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.