CLI for agents
Human-oriented CLIs often block agents: interactive prompts, huge upfront docs, and help text without copy-pasteable examples. Prefer patterns that work headlessly and compose in pipelines.
Non-interactive first
- Every input should be expressible as a flag or flag value. Do not require arrow keys, menus, or timed prompts.
- If flags are missing, then fall back to interactive mode—not the other way around.
Bad: mycli deploy → ? Which environment? (use arrow keys)
Good: mycli deploy --env staging
Discoverability without dumping context
- Agents discover subcommands incrementally:
mycli, then mycli deploy --help. Do not print the entire manual on every run.
- Let each subcommand own its documentation so unused commands stay out of context.
--help that works
- Every subcommand has
--help.
- Every
--help includes Examples with real invocations. Examples do more than prose for pattern-matching.
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
stdin, flags, and pipelines
- Accept stdin where it makes sense (e.g.
cat config.json | mycli config import --stdin).
- Avoid odd positional ordering and avoid falling back to interactive prompts for missing values.
- Support chaining:
mycli deploy --env staging --tag $(mycli build --output tag-only).
Fail fast with actionable errors
- On missing required flags: exit immediately with a clear message and a correct example invocation, not a hang.
Error: No image tag specified.
mycli deploy --env staging --tag <image-tag>
Available tags: mycli build list --output tags
Idempotency
- Agents retry often. The same successful command run twice should be safe (no-op or explicit "already done"), not duplicate side effects.
Destructive actions
- Add
--dry-run (or equivalent) so agents can preview plans before committing.
- Offer
--yes / --force to skip confirmations while keeping the safe default for humans.
Predictable structure
- Use a consistent pattern everywhere, e.g.
resource + verb: if mycli service list exists, mycli deploy list and mycli config list should follow the same shape.
Success output
- On success, return machine-useful data: IDs, URLs, durations. Plain text is fine; avoid relying on decorative output alone.
deployed v1.2.3 to staging
url: https://staging.myapp.com
deploy_id: dep_abc123
duration: 34s
When reviewing an existing CLI
- Check: non-interactive path, layered help, examples on
--help, stdin/pipeline story, error messages with invocations, idempotency, dry-run, confirmation bypass flags, consistent command structure, structured success output.
1---
2name: cli-for-agents
3description: >-
4 Designs or reviews CLIs so coding agents can run them reliably: non-interactive
5 flags, layered --help with examples, stdin/pipelines, fast actionable errors,
6 idempotency, dry-run, and predictable structure. Use when building a CLI,
7 adding commands, writing --help, or when the user mentions agents, terminals,
8 or automation-friendly CLIs.
9---
10
11# CLI for agents
12
13Human-oriented CLIs often block agents: interactive prompts, huge upfront docs, and help text without copy-pasteable examples. Prefer patterns that work headlessly and compose in pipelines.
14
15## Non-interactive first
16
17- Every input should be expressible as a flag or flag value. Do not require arrow keys, menus, or timed prompts.
18- If flags are missing, **then** fall back to interactive mode—not the other way around.
19
20**Bad:** `mycli deploy` → `? Which environment? (use arrow keys)`
21**Good:** `mycli deploy --env staging`
22
23## Discoverability without dumping context
24
25- Agents discover subcommands incrementally: `mycli`, then `mycli deploy --help`. Do not print the entire manual on every run.
26- Let each subcommand own its documentation so unused commands stay out of context.
27
28## `--help` that works
29
30- Every subcommand has `--help`.
31- Every `--help` includes **Examples** with real invocations. Examples do more than prose for pattern-matching.
32
33```text
34Options:
35 --env Target environment (staging, production)
36 --tag Image tag (default: latest)
37 --force Skip confirmation
38
39Examples:
40 mycli deploy --env staging
41 mycli deploy --env production --tag v1.2.3
42 mycli deploy --env staging --force
43```
44
45## stdin, flags, and pipelines
46
47- Accept stdin where it makes sense (e.g. `cat config.json | mycli config import --stdin`).
48- Avoid odd positional ordering and avoid falling back to interactive prompts for missing values.
49- Support chaining: `mycli deploy --env staging --tag $(mycli build --output tag-only)`.
50
51## Fail fast with actionable errors
52
53- On missing required flags: exit immediately with a clear message and a **correct example invocation**, not a hang.
54
55```text
56Error: No image tag specified.
57 mycli deploy --env staging --tag <image-tag>
58 Available tags: mycli build list --output tags
59```
60
61## Idempotency
62
63- Agents retry often. The same successful command run twice should be safe (no-op or explicit "already done"), not duplicate side effects.
64
65## Destructive actions
66
67- Add `--dry-run` (or equivalent) so agents can preview plans before committing.
68- Offer `--yes` / `--force` to skip confirmations while keeping the safe default for humans.
69
70## Predictable structure
71
72- Use a consistent pattern everywhere, e.g. `resource` + `verb`: if `mycli service list` exists, `mycli deploy list` and `mycli config list` should follow the same shape.
73
74## Success output
75
76- On success, return machine-useful data: IDs, URLs, durations. Plain text is fine; avoid relying on decorative output alone.
77
78```text
79deployed v1.2.3 to staging
80url: https://staging.myapp.com
81deploy_id: dep_abc123
82duration: 34s
83```
84
85## When reviewing an existing CLI
86
87- Check: non-interactive path, layered help, examples on `--help`, stdin/pipeline story, error messages with invocations, idempotency, dry-run, confirmation bypass flags, consistent command structure, structured success output.
cursor