cli-designer

Files (10)

• SKILL.md
• cli-help-example.txt · assets/
• cli-review-template.md · assets/
• automation-modes.md · references/
• destructive-operations.md · references/
• flags-and-defaults.md · references/
• hierarchy-and-naming.md · references/
• output-contract.md · references/
• standards.md · references/
• check_cli_surface.py · scripts/

SKILL.md (first lines)

# CLI Designer

## Mission

A command-line interface is often the de facto product UX: the first and only surface many users touch. Design and audit CLIs as products, not plumbing. Every command, flag, prompt, and byte of output is product surface.

Human users need a surface that is predictable, discoverable, and forgiving. Automation needs one that is deterministic, parseable, and versioned. The same binary serves both.

For error text and recovery design, use the `error-experience` skill if available. For config model design, use the `configuration-dx` skill if available. For release compatibility of CLI output, use the `release-guardian` skill if available.

## Core principle

Great for humans, stable for automation.

Humans get interaction: sane defaults, helpful prompts, colors, progress, forgiving errors. Automation gets the contract: `--json` output with stable field names, documented exit codes, no prompts, no colors on pipes. When the two conflict, the interaction follows the human and the bytes follow the automation.

Never change a byte that a script depends on without a release event. Never prompt when stdin is not a TTY and no interactive mode was requested.

## References

Read `references/standards.md` for the canonical thresholds, severity vocabulary, and release gates.

Read `references/hierarchy-and-naming.md` when designing or reviewing command hierarchy, naming, and alias policy.

Read `references/flags-and-defaults.md` when reviewing flag shapes, defaults, deprecation, and config-vs-flag precedence.

Read `references/output-contract.md` when auditing stdout/stderr discipline, exit codes, JSON output, and TTY behavior.

Read `references/automation-modes.md` when auditing non-interactive behavior and scripted usage.

Read `references/destructive-operations.md` when auditing delete, overwrite, and other destructive operations.

## CLI design workflow

### 1. Inventory the command surface

Run `scripts/check_cli_surface.py` against the CLI's source tree for a first-pass catalog, or pass `--helpfile` a captured `--help` text when only the binary or docs are available.

Verify:

- every public command, flag, and argument is enumerated, including legacy and hidden commands
- captured help matches the shipped binary; regenerate help text, never edit it by hand
- `--version` output and autocomplete definitions are captured and reviewed

Never audit from memory. Help output and source are the ground truth.

### 2. Audit hierarchy and naming

Read `references/hierarchy-and-naming.md`.

Verify:

- structure is verb-noun: actions are verbs, targets are nouns (`sync dataset`, `delete dataset`)
- one verb per concept; no near-synonym commands for the same action
- aliases exist only for established muscle memory and are documented
- a command run with no arguments shows help or runs a safe read-only default
- the tree stays shallow; depth beyond two levels is a finding

### 3. Audit flags, arguments, and defaults

Read `references/flags-and-defaults.md`.

Verify:

- boolean flags take no values; never `--force true`
- short flags exist only for the most common options and do not collide
- defaults are the safe choice, never the dangerous one
- deprecated flags still work and warn with the replacement and removal version
- flag-over-config-over-environment precedence is documented and implemented in one code path
- a missing required value fails fast with a usage error, never a mid-run prompt

### 4. Audit the I/O contract

Read `references/output-contract.md`.

Verify:

- data on stdout only; diagnostics, progress, and logs on stderr
- `--json` exists on every command that emits data, with stable field names
- exit codes are documented per command and correct for success, usage, and each failure class
- color and progress appear only on a TTY; pipes and redirection stay clean
- piped output is line- or JSON-complete; a consumer never loses bytes

### 5. Audit automation modes

Read `references/automation-modes.md`.

Verify:

- every prompt has a non-interactive path: `--yes`, `--no-input`, or a documented flag
- the tool never hangs waiting for input when stdin is closed or non-interactive
- CI-safe behavior is verified, not assumed
- scripted usage is exercised: `cmd --json | jq`, `cmd 2>/dev/null`, `cmd < /dev/null`
- repeated runs are idempotent or documented as not

### 6. Audit destructive operations

Read `references/destructive-operations.md`.

Verify:

- destructive commands confirm before acting in interactive mode
- automation bypasses confirmation only via an explicit `--force` or `--yes`, never implicitly
- a dry-run mode exists or the operation reports what it will change before acting
- reversibility is stated: what is lost, what survives, how to verify
- guardrails scale with blast radius; the more irreversible, the more friction

### 7. Design improvements

Prioritize every finding by severity from `references/standards.md`. Do not polish cosmetics before P0/P1 issues are resolved.

- group related changes into one coherent revision of the surface
- preserve the automation contract: deprecate instead of breaking, warn in one release, remove in a major
- ship help text, man page, autocomplete, and tests in the same change as the command or flag
- re-run the inventory and the automation test matrix after every change

## Output contract

Machine-readable output is a contract, not a convenience.

From devarispbrown/devex-skills, MIT.

More from devarispbrown/devex-skills