CLI UX Review
Audits a CLI against a fixed rubric, from the perspective of a non-developer
who has never used it.
When to invoke
- "CLI UX audit" / "review my CLI" / "is this CLI intuitive"
- Before every CLI release
- After adding or changing any CLI command
The frame
Every command output must answer three questions:
What is the situation? · What are the next steps? · What can I do?
Quality bar: a command ends the way Codex ends a session — a line of plain
status, then the exact next command, rendered in a distinct colour so the eye
lands on "type this."
Rubric (score each command against all 7)
- Next step present. Every success / terminal state ends with the next
command, or an explicit "you are done." No command stalls silently.
- Commands are colour-highlighted. Runnable commands render in one
consistent accent (cyan + bold). Never bare text, never literal backticks.
- No raw internals. No enum values, state codes, or jargon in user output.
Human words plus a one-line legend ("dirty" becomes "local edits").
- No silent hang. Long-running or stdio commands announce themselves on a
TTY, so the terminal never looks frozen.
- Consistent primitives. One glyph set, one row/table helper, one next-step
block, shared across commands, not re-invented per command.
- Errors embed the fix. Every error names the exact command that resolves
it.
- Guided first run. Bare invocation or a not-logged-in state shows a
numbered quickstart.
How to run
- Inventory every command and every output path. Read the source, not just
--help.
- For each command, walk the success path, every error path, and empty states.
- Score against the 7 rubric points. Cite
file:line for each finding.
- Where it fails, write the concrete before / after with the exact strings.
- Output: cross-cutting issues, a per-command table, ranked before/after fixes,
and an execution plan.
Output format
A findings doc: TL;DR and core problem, cross-cutting issues table, per-command
findings, before/after for each fix, execution plan. Never write "looks fine"
without having walked the actual output path that proves it.
1---2name: cli-ux-review3description: Audit a command-line tool for user-friendliness — clear situation / next-step / options in every output, colour-highlighted runnable commands, no raw jargon, no silent hangs. Invoke for "CLI UX audit", "review my CLI", "is this CLI intuitive", or before any CLI release.4---56# CLI UX Review78Audits a CLI against a fixed rubric, from the perspective of a non-developer9who has never used it.1011## When to invoke12- "CLI UX audit" / "review my CLI" / "is this CLI intuitive"13- Before every CLI release14- After adding or changing any CLI command1516## The frame17Every command output must answer three questions:18**What is the situation? · What are the next steps? · What can I do?**1920Quality bar: a command ends the way Codex ends a session — a line of plain21status, then the exact next command, rendered in a distinct colour so the eye22lands on "type this."2324## Rubric (score each command against all 7)251. **Next step present.** Every success / terminal state ends with the next26 command, or an explicit "you are done." No command stalls silently.272. **Commands are colour-highlighted.** Runnable commands render in one28 consistent accent (cyan + bold). Never bare text, never literal backticks.293. **No raw internals.** No enum values, state codes, or jargon in user output.30 Human words plus a one-line legend ("dirty" becomes "local edits").314. **No silent hang.** Long-running or stdio commands announce themselves on a32 TTY, so the terminal never looks frozen.335. **Consistent primitives.** One glyph set, one row/table helper, one next-step34 block, shared across commands, not re-invented per command.356. **Errors embed the fix.** Every error names the exact command that resolves36 it.377. **Guided first run.** Bare invocation or a not-logged-in state shows a38 numbered quickstart.3940## How to run411. Inventory every command and every output path. Read the source, not just42 `--help`.432. For each command, walk the success path, every error path, and empty states.443. Score against the 7 rubric points. Cite `file:line` for each finding.454. Where it fails, write the concrete before / after with the exact strings.465. Output: cross-cutting issues, a per-command table, ranked before/after fixes,47 and an execution plan.4849## Output format50A findings doc: TL;DR and core problem, cross-cutting issues table, per-command51findings, before/after for each fix, execution plan. Never write "looks fine"52without having walked the actual output path that proves it.
getedgehq