/cli-for-agent
Human-oriented CLIs 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.
Adapted from cursor/plugins
cli-for-agent/skills/cli-for-agents/SKILL.md (MIT, © Cursor). Vendored per
the superskills imported-skills rule; changes here do not track upstream.
1---2name: cli-for-agent3version: 1.0.04description: |5 Design or review CLIs so coding agents can run them reliably: non-interactive6 flags first, layered --help with real copy-pasteable examples, stdin/pipeline7 support, fail-fast errors that include a correct invocation, idempotency,8 --dry-run/--yes for destructive actions, and machine-useful success output.9 Use when building a CLI, adding commands or subcommands, writing --help10 text, or when asked for an "agent-friendly CLI". Not for GUIs, TUIs, or11 library APIs (no CLI surface to design).12metadata.upstream: https://github.com/cursor/plugins (cli-for-agent/skills/cli-for-agents, MIT)13triggers:14 - agent-friendly cli15 - cli for agents16 - build a cli17 - add a subcommand18 - write --help19allowed-tools:20 - Bash21 - Read22 - Write23 - Edit24 - Grep25 - Glob26metadata:27 source: https://skillmd.com/skills/ariadoss/cli-for-agent28---2930# /cli-for-agent3132Human-oriented CLIs block agents: interactive prompts, huge upfront docs, and33help text without copy-pasteable examples. Prefer patterns that work headlessly34and compose in pipelines.3536## Non-interactive first3738- Every input should be expressible as a flag or flag value. Do not require39 arrow keys, menus, or timed prompts.40- If flags are missing, **then** fall back to interactive mode — not the other41 way around.4243**Bad:** `mycli deploy` → `? Which environment? (use arrow keys)`44**Good:** `mycli deploy --env staging`4546## Discoverability without dumping context4748- Agents discover subcommands incrementally: `mycli`, then `mycli deploy49 --help`. Do not print the entire manual on every run.50- Let each subcommand own its documentation so unused commands stay out of51 context.5253## `--help` that works5455- Every subcommand has `--help`.56- Every `--help` includes **Examples** with real invocations. Examples do more57 than prose for pattern-matching.5859```text60Options:61 --env Target environment (staging, production)62 --tag Image tag (default: latest)63 --force Skip confirmation6465Examples:66 mycli deploy --env staging67 mycli deploy --env production --tag v1.2.368 mycli deploy --env staging --force69```7071## stdin, flags, and pipelines7273- Accept stdin where it makes sense (e.g. `cat config.json | mycli config74 import --stdin`).75- Avoid odd positional ordering and avoid falling back to interactive prompts76 for missing values.77- Support chaining: `mycli deploy --env staging --tag $(mycli build --output78 tag-only)`.7980## Fail fast with actionable errors8182- On missing required flags: exit immediately with a clear message and a83 **correct example invocation**, not a hang.8485```text86Error: No image tag specified.87 mycli deploy --env staging --tag <image-tag>88 Available tags: mycli build list --output tags89```9091## Idempotency9293- Agents retry often. The same successful command run twice should be safe94 (no-op or explicit "already done"), not duplicate side effects.9596## Destructive actions9798- Add `--dry-run` (or equivalent) so agents can preview plans before99 committing.100- Offer `--yes`/`--force` to skip confirmations while keeping the safe default101 for humans.102103## Predictable structure104105- Use a consistent pattern everywhere, e.g. `resource` + `verb`: if `mycli106 service list` exists, `mycli deploy list` and `mycli config list` should107 follow the same shape.108109## Success output110111- On success, return machine-useful data: IDs, URLs, durations. Plain text is112 fine; avoid relying on decorative output alone.113114```text115deployed v1.2.3 to staging116url: https://staging.myapp.com117deploy_id: dep_abc123118duration: 34s119```120121## When reviewing an existing CLI122123- Check: non-interactive path, layered help, examples on `--help`,124 stdin/pipeline story, error messages with invocations, idempotency,125 dry-run, confirmation bypass flags, consistent command structure,126 structured success output.127128---129130Adapted from [cursor/plugins](https://github.com/cursor/plugins)131`cli-for-agent/skills/cli-for-agents/SKILL.md` (MIT, © Cursor). Vendored per132the superskills imported-skills rule; changes here do not track upstream.