Command-Line Tool
Build a command-line tool with subcommands, flags, arguments, help text, and proper exit codes. Designs the CLI UX FIRST — the command surface, flags with defaults, positional args, help/usage output, and exit-code conventions — because a CLI's contract is its interface, then implements argument parsing and command logic, then writes tests for parsing, help, happy paths, and error exits. Covers argv parsing, subcommands, --flags and -short forms, --help, stdin/stdout/stderr conventions, and non-zero exit codes on error.
Steps
Entry step: ux-scope. Each step names the specialist role it wants; the full working prompt is expandable.
- CLI UX scopeplannerentry
lock the command surface, flags, args, exit codes
Show working prompt
Design the command-line interface before any logic — the interface IS the contract. Step 1: Enumerate the commands/subcommands and what each does. Step 2: For each, list the positional arguments (required vs optional) and the flags (`--long`, `-s` short form, type, default value, whether it takes a value). Step 3: Draft the exact `--help`/usage text the tool prints, including a one-line synopsis per command. Step 4: Define the IO and exit-code contract: what goes to stdout vs stderr, exit 0 on success, distinct non-zero codes for usage errors vs runtime errors. Step 5: Write a numbered acceptance-criteria checklist of 5-9 items (e.g. 'running with no args or --help prints usage and exits 0', 'an unknown flag prints an error to stderr and exits non-zero', 'the primary command produces the documented output'). `write_task_note` the command spec + checklist and write the same to the produces path. No implementation yet.
- Build the CLIdeveloper
implement parsing + command logic
Show working prompt
Implement the CLI in a single runnable source file with a real entry point. Step 1: Parse argv into commands, positional args, and flags exactly as scoped — support both long and short flag forms and apply defaults. Step 2: Implement each command's logic; write normal output to stdout and diagnostics/errors to stderr. Step 3: Wire `--help` (and bare invocation) to print the usage text and exit 0; on unknown command/flag or missing required arg, print a clear error to stderr and exit non-zero. Step 4: Ensure the process exits with the documented code in every path. On a loop-back, fix only the named gaps without regressing working commands. `write_task_note` the file path and which criteria now pass.
- Write CLI testsdeveloper
test parsing, help, happy paths, error exits
Show working prompt
Write tests that invoke the CLI and inspect output + exit code. Step 1: Assert `--help` and bare invocation print usage and exit 0. Step 2: Assert each command's happy path produces the documented stdout and exits 0. Step 3: Assert error cases (unknown flag, missing required arg, bad value) print to stderr and exit non-zero with the right code. Step 4: Assert flag parsing handles long form, short form, and defaults. Capture stdout/stderr separately. `write_task_note` the test file path and pass/fail count.
- Evaluatereviewer
Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.
Show working prompt
Run the tests and invoke the CLI directly. For EACH acceptance criterion: confirm --help/usage works and exits 0, confirm each command's output matches the spec, confirm errors go to stderr with a non-zero exit, and confirm flag parsing (long, short, defaults) works. Write PASS/FAIL per criterion. Then route — this is the whole point of the loop: - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`. - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "build" })` to loop back. The builder fixes exactly those gaps. Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in. - Finishdeveloper
All acceptance criteria met. Stamp a short summary and report DONE.
Show working prompt
Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.
Triggers
Phrases that suggest this craftbook to a crew.
- build a cli tool
- command line tool
- make a terminal command
- cli with subcommands
- argv parser
Source
View this craftbook on GitHub · MIT license