Writing Agent-Friendly CLIs
Use this skill when building, reviewing, or redesigning a CLI or agentic interface meant to serve both humans and coding agents. Do not use it merely to decide whether to prefix an arbitrary command with environment variables.
Design principles
Model the CLI after Notion's ntn: one tool that is pleasant for humans, scriptable for shells, and predictable for agents.
- Progressive disclosure — make the common path short, with deeper help/docs/spec output behind flags or subcommands.
- Actionable errors — say what failed, why it likely failed, and the exact next command or flag to try.
- Separate data from messages — write machine-readable data to stdout; write progress, warnings, prompts, and diagnostics to stderr.
- Interactive and non-interactive modes — prompts are fine for humans, but every prompt must have a flag/env/stdin equivalent for agents and CI.
Output contract
- Provide
--json for structured output on list/get/status commands.
- Provide plain stable output when JSON is too heavy, e.g. TSV with
--plain.
- Keep stdout parseable: no spinners, colors, banners, or prose in data mode.
- Put progress and diagnostics on stderr.
- Redact secrets in logs by default; make unsafe verbose modes explicit and scary.
Command shape
- Prefer predictable nouns and verbs:
tool workers list, tool pages get <id>.
- Support
--help at every level.
- Add
doctor for auth/config/network checks.
- Add
--verbose for source chains and request/response metadata.
- Add
--yes for destructive confirmations in non-interactive runs.
- Add
--no-watch, --no-browser, --no-install, or equivalent escape hatches for commands that would otherwise block.
Input contract
- Accept stdin for large JSON/Markdown payloads.
- Accept
--data or --file for scriptable payloads.
- Accept env vars for CI/auth overrides, but keep flags higher clarity for one-off commands.
- Avoid requiring TTY-only flows for setup; provide a polling, token, or copied-code path.
Agent affordances
- Document examples agents can paste directly.
- Provide live reference commands where possible:
api ls, --spec, --docs, --json.
- Make errors self-recovering: include missing config paths, required flags, and safe retry commands.
- Keep command output deterministic unless watch/stream mode is explicitly requested.
Checklist
1---2name: writing-agent-friendly-clis3description: Write, design, or review agent-friendly CLIs and agentic interfaces for humans, scripts, and coding agents, with progressive disclosure, structured output, actionable errors, stdout/stderr separation, and explicit non-interactive modes.4---56# Writing Agent-Friendly CLIs78Use this skill when building, reviewing, or redesigning a CLI or agentic interface meant to serve both humans and coding agents. Do not use it merely to decide whether to prefix an arbitrary command with environment variables.910## Design principles1112Model the CLI after Notion's `ntn`: one tool that is pleasant for humans, scriptable for shells, and predictable for agents.13141. **Progressive disclosure** — make the common path short, with deeper help/docs/spec output behind flags or subcommands.152. **Actionable errors** — say what failed, why it likely failed, and the exact next command or flag to try.163. **Separate data from messages** — write machine-readable data to stdout; write progress, warnings, prompts, and diagnostics to stderr.174. **Interactive and non-interactive modes** — prompts are fine for humans, but every prompt must have a flag/env/stdin equivalent for agents and CI.1819## Output contract2021- Provide `--json` for structured output on list/get/status commands.22- Provide plain stable output when JSON is too heavy, e.g. TSV with `--plain`.23- Keep stdout parseable: no spinners, colors, banners, or prose in data mode.24- Put progress and diagnostics on stderr.25- Redact secrets in logs by default; make unsafe verbose modes explicit and scary.2627## Command shape2829- Prefer predictable nouns and verbs: `tool workers list`, `tool pages get <id>`.30- Support `--help` at every level.31- Add `doctor` for auth/config/network checks.32- Add `--verbose` for source chains and request/response metadata.33- Add `--yes` for destructive confirmations in non-interactive runs.34- Add `--no-watch`, `--no-browser`, `--no-install`, or equivalent escape hatches for commands that would otherwise block.3536## Input contract3738- Accept stdin for large JSON/Markdown payloads.39- Accept `--data` or `--file` for scriptable payloads.40- Accept env vars for CI/auth overrides, but keep flags higher clarity for one-off commands.41- Avoid requiring TTY-only flows for setup; provide a polling, token, or copied-code path.4243## Agent affordances4445- Document examples agents can paste directly.46- Provide live reference commands where possible: `api ls`, `--spec`, `--docs`, `--json`.47- Make errors self-recovering: include missing config paths, required flags, and safe retry commands.48- Keep command output deterministic unless watch/stream mode is explicitly requested.4950## Checklist5152- [ ] Common human path is one short command.53- [ ] Every interactive prompt has a non-interactive equivalent.54- [ ] Data mode writes only data to stdout.55- [ ] Logs/progress/errors go to stderr.56- [ ] `--json` exists for agent parsing.57- [ ] Errors include the next concrete fix.58- [ ] Secrets are redacted by default.
edmundmiller