CLI Development
This skill grounds CLI work in the Command Line Interface
Guidelines — an open-source guide maintained by Aanand
Prasad, Ben Firshman, Carl Tashian, and Eva Parish that updates traditional
UNIX principles for modern human-first command-line tools.
clig.dev is a single canonical page. The full text is published under
https://clig.dev/ (HTML) and https://clig.dev/llms.txt (machine-readable
markdown). This skill mirrors the structure of that guide as a sitemap plus
per-section reference files, and instructs you to fetch the canonical source
before citing rules so your recommendations track upstream changes.
When this skill applies
Use it whenever the work touches CLI surface:
- Design — proposing a new CLI tool or subcommand layout; choosing flag
names, defaults, or argument shape; deciding what configuration goes in
flags, environment variables, or config files; naming a binary.
- Implementation — wiring stdout/stderr; emitting help text and errors;
picking an argument-parsing library; handling Ctrl-C; deciding when to
prompt; gating dangerous operations.
- Review — reading a pull request that adds or modifies CLI surface;
pointing reviewers at the specific guideline a change conflicts with.
- Specification — drafting CLI specs, RFCs, design documents, or
architectural diagrams that include a command-line interface.
- QA — testing a CLI for behaviors clig.dev calls out (TTY detection,
NO_COLOR, --no-input, exit codes, error rewriting, signal handling,
pager behavior).
- Discussion — answering questions about CLI conventions, defending or
critiquing a CLI design choice, comparing competing approaches.
If the conversation involves a CLI surface and the question is "what is the
right way to do this?", consult clig.dev before answering.
Workflow
Locate the relevant sections. Read references/sitemap.md.
It indexes every clig.dev anchor with a one-line description. Pick the
sections that match the work — usually one to four.
Pull the canonical source. clig.dev evolves; do not rely on the local
reference copy alone for binding recommendations. Fetch the live content:
- Preferred: the
tavily-extract skill, with the URL
https://clig.dev/llms.txt and a query naming the section
(e.g., "arguments and flags"). This returns clean markdown.
- Alternative:
WebFetch against https://clig.dev/llms.txt or
https://clig.dev/#<anchor> with a prompt naming the section.
- Offline fallback: the bundled per-section file under
references/ is a snapshot of the guideline text. Use it when network
fetches fail; flag the recommendation as based on a snapshot rather
than live content.
Read the matched section in full. Each section is short. Read the
bundled reference file or the fetched text end-to-end. The guidelines
are interlinked — a recommendation about flags will often defer to the
Output or Configuration section.
Apply the guidance to the task. Translate the rule into a concrete
recommendation, code change, or review comment. State the rule, then the
reasoning, then the application.
Cite the anchor. When you recommend or critique, link to the
specific clig.dev anchor — e.g., https://clig.dev/#arguments-and-flags
— so the reader can verify or read more. Citations are part of the
deliverable, not an optional flourish.
Citing rules
When you state a rule, name where it comes from. Format:
"Disable color when stdout is not a TTY (clig.dev: Output)."
If the user is reviewing code, quote the exact rule heading from clig.dev
(the bold lead-in sentences in the guide, like "Disable color if your
program is not in a terminal or the user requested it.") so the comment
is grounded in primary text rather than your paraphrase.
What this skill does not cover
clig.dev is explicit about its scope: it does not cover full-screen
terminal programs (vim, emacs, ncurses TUIs). It is also language- and
framework-agnostic. If the user is asking about TUI design or about a
specific framework's idioms, clig.dev covers the underlying CLI etiquette
but not the framework specifics.
Reference layout
| File |
Covers |
references/sitemap.md |
Index of every clig.dev anchor with canonical URL + one-line summary. Read this first. |
references/philosophy.md |
The nine philosophical principles (human-first design, composability, consistency, discoverability, conversation, robustness, empathy, chaos). |
references/the-basics.md |
Argument parsing libraries, exit codes, stdout vs stderr. The non-negotiable foundation. |
references/help.md |
Help text content, formatting, suggestions when input is wrong, behavior on -h/--help. |
references/documentation.md |
Web docs, terminal docs, man pages. |
references/output.md |
Human vs machine output, --plain, --json, color, NO_COLOR, pagers, ASCII art for density. |
references/errors.md |
Rewriting errors for humans, signal-to-noise, debug info, bug-report flow. |
references/arguments-and-flags.md |
Flag naming conventions, common flags, confirmation for dangerous actions, secrets handling. |
references/interactivity.md |
TTY checks, --no-input, password prompts, escape paths. |
references/subcommands.md |
When subcommands help, naming consistency, noun-verb vs verb-noun. |
references/robustness.md |
Input validation, responsiveness budgets, progress, parallelism, timeouts, recovery, crash-only design. |
references/future-proofing.md |
Additive changes, deprecation, abbreviations, time bombs. |
references/signals.md |
Ctrl-C handling, double-Ctrl-C semantics. |
references/configuration.md |
XDG base directories, precedence order, project-level config. |
references/environment-variables.md |
Naming, .env usage, well-known variables, why secrets do not belong in env vars. |
references/naming.md |
Picking a memorable, typeable, lowercase command name. |
references/distribution.md |
Single-binary preference, easy uninstall. |
references/analytics.md |
Consent for telemetry, alternatives to collecting analytics. |
The bundled references are the same prose clig.dev publishes. They are
provided for offline use and as a stable cite-able anchor. The canonical
text remains https://clig.dev/ and https://clig.dev/llms.txt.
1---2name: cli-development3description: CLI development reference grounded in https://clig.dev. Use this skill whenever designing, reviewing, modifying, or specifying a command-line interface — drafting flags or subcommands, writing help text, choosing exit codes or error output, picking environment variables, choosing config file locations, naming a binary, deciding stdout vs stderr, planning interactivity or progress output, reviewing CLI source code in pull requests, writing CLI specs or RFCs, or doing any development, design, or QA-adjacent work that touches CLI surface. The skill provides a sitemap of clig.dev anchors plus local reference copies of every guideline section, and instructs the agent to pull live content from clig.dev before citing rules so recommendations stay current.4license: EUPL-1.25---67# CLI Development89This skill grounds CLI work in the [Command Line Interface10Guidelines](https://clig.dev) — an open-source guide maintained by Aanand11Prasad, Ben Firshman, Carl Tashian, and Eva Parish that updates traditional12UNIX principles for modern human-first command-line tools.1314clig.dev is a single canonical page. The full text is published under15`https://clig.dev/` (HTML) and `https://clig.dev/llms.txt` (machine-readable16markdown). This skill mirrors the structure of that guide as a sitemap plus17per-section reference files, and instructs you to fetch the canonical source18before citing rules so your recommendations track upstream changes.1920## When this skill applies2122Use it whenever the work touches CLI surface:2324- **Design** — proposing a new CLI tool or subcommand layout; choosing flag25 names, defaults, or argument shape; deciding what configuration goes in26 flags, environment variables, or config files; naming a binary.27- **Implementation** — wiring stdout/stderr; emitting help text and errors;28 picking an argument-parsing library; handling Ctrl-C; deciding when to29 prompt; gating dangerous operations.30- **Review** — reading a pull request that adds or modifies CLI surface;31 pointing reviewers at the specific guideline a change conflicts with.32- **Specification** — drafting CLI specs, RFCs, design documents, or33 architectural diagrams that include a command-line interface.34- **QA** — testing a CLI for behaviors clig.dev calls out (TTY detection,35 `NO_COLOR`, `--no-input`, exit codes, error rewriting, signal handling,36 pager behavior).37- **Discussion** — answering questions about CLI conventions, defending or38 critiquing a CLI design choice, comparing competing approaches.3940If the conversation involves a CLI surface and the question is "what is the41right way to do this?", consult clig.dev before answering.4243## Workflow44451. **Locate the relevant sections.** Read [`references/sitemap.md`](references/sitemap.md).46 It indexes every clig.dev anchor with a one-line description. Pick the47 sections that match the work — usually one to four.48492. **Pull the canonical source.** clig.dev evolves; do not rely on the local50 reference copy alone for binding recommendations. Fetch the live content:5152 - **Preferred:** the `tavily-extract` skill, with the URL53 `https://clig.dev/llms.txt` and a query naming the section54 (e.g., "arguments and flags"). This returns clean markdown.55 - **Alternative:** `WebFetch` against `https://clig.dev/llms.txt` or56 `https://clig.dev/#<anchor>` with a prompt naming the section.57 - **Offline fallback:** the bundled per-section file under58 `references/` is a snapshot of the guideline text. Use it when network59 fetches fail; flag the recommendation as based on a snapshot rather60 than live content.61623. **Read the matched section in full.** Each section is short. Read the63 bundled reference file or the fetched text end-to-end. The guidelines64 are interlinked — a recommendation about flags will often defer to the65 `Output` or `Configuration` section.66674. **Apply the guidance to the task.** Translate the rule into a concrete68 recommendation, code change, or review comment. State the rule, then the69 reasoning, then the application.70715. **Cite the anchor.** When you recommend or critique, link to the72 specific clig.dev anchor — e.g., `https://clig.dev/#arguments-and-flags`73 — so the reader can verify or read more. Citations are part of the74 deliverable, not an optional flourish.7576## Citing rules7778When you state a rule, name where it comes from. Format:7980> "Disable color when stdout is not a TTY ([clig.dev: Output](https://clig.dev/#output))."8182If the user is reviewing code, quote the exact rule heading from clig.dev83(the bold lead-in sentences in the guide, like "**Disable color if your84program is not in a terminal or the user requested it.**") so the comment85is grounded in primary text rather than your paraphrase.8687## What this skill does not cover8889clig.dev is explicit about its scope: it does not cover full-screen90terminal programs (vim, emacs, ncurses TUIs). It is also language- and91framework-agnostic. If the user is asking about TUI design or about a92specific framework's idioms, clig.dev covers the underlying CLI etiquette93but not the framework specifics.9495## Reference layout9697| File | Covers |98|------|--------|99| [`references/sitemap.md`](references/sitemap.md) | Index of every clig.dev anchor with canonical URL + one-line summary. Read this first. |100| [`references/philosophy.md`](references/philosophy.md) | The nine philosophical principles (human-first design, composability, consistency, discoverability, conversation, robustness, empathy, chaos). |101| [`references/the-basics.md`](references/the-basics.md) | Argument parsing libraries, exit codes, stdout vs stderr. The non-negotiable foundation. |102| [`references/help.md`](references/help.md) | Help text content, formatting, suggestions when input is wrong, behavior on `-h`/`--help`. |103| [`references/documentation.md`](references/documentation.md) | Web docs, terminal docs, man pages. |104| [`references/output.md`](references/output.md) | Human vs machine output, `--plain`, `--json`, color, `NO_COLOR`, pagers, ASCII art for density. |105| [`references/errors.md`](references/errors.md) | Rewriting errors for humans, signal-to-noise, debug info, bug-report flow. |106| [`references/arguments-and-flags.md`](references/arguments-and-flags.md) | Flag naming conventions, common flags, confirmation for dangerous actions, secrets handling. |107| [`references/interactivity.md`](references/interactivity.md) | TTY checks, `--no-input`, password prompts, escape paths. |108| [`references/subcommands.md`](references/subcommands.md) | When subcommands help, naming consistency, noun-verb vs verb-noun. |109| [`references/robustness.md`](references/robustness.md) | Input validation, responsiveness budgets, progress, parallelism, timeouts, recovery, crash-only design. |110| [`references/future-proofing.md`](references/future-proofing.md) | Additive changes, deprecation, abbreviations, time bombs. |111| [`references/signals.md`](references/signals.md) | Ctrl-C handling, double-Ctrl-C semantics. |112| [`references/configuration.md`](references/configuration.md) | XDG base directories, precedence order, project-level config. |113| [`references/environment-variables.md`](references/environment-variables.md) | Naming, `.env` usage, well-known variables, why secrets do not belong in env vars. |114| [`references/naming.md`](references/naming.md) | Picking a memorable, typeable, lowercase command name. |115| [`references/distribution.md`](references/distribution.md) | Single-binary preference, easy uninstall. |116| [`references/analytics.md`](references/analytics.md) | Consent for telemetry, alternatives to collecting analytics. |117118The bundled references are the same prose clig.dev publishes. They are119provided for offline use and as a stable cite-able anchor. The canonical120text remains `https://clig.dev/` and `https://clig.dev/llms.txt`.
synapseradio