{"version":"1.1.0","schema":"https://oneagentaday.com/api/schema.json","agent":{"title":"CLI Help Rewriter","slug":"cli-help-rewriter","date":"2026-09-26","issue":22,"category":"devtools","categoryLabel":"Dev Tools","tags":["cli","docs","dx"],"difficulty":"easy","runtimes":["ChatGPT","Claude","Gemini"],"excerpt":"Paste --help output. Get three copy-paste examples, the flags that matter, and the ones that should stay hidden.","problem":"The help text lists forty flags in alphabetical order, and the one command a person needs to copy is not among them.","videoUrl":null,"url":"https://oneagentaday.com/agents/cli-help-rewriter","apiUrl":"https://oneagentaday.com/api/agents/cli-help-rewriter.json","promptUrl":"https://oneagentaday.com/agents/cli-help-rewriter/prompt.txt","configUrl":null,"configFilename":null,"license":"CC-BY-4.0","howItWorks":"Help text is a dictionary. People need a sentence they can paste. You give it the help for one command and the example you wish it had led with. It returns three examples using only flags from the paste, then a short list of the flags that belong in those examples.\n\nUnfinished flags stay out. The rewriter does not invent a subcommand or a default you did not show. The binary name is the one you typed.\n\nPut the examples above the flag list. If a dry run exists, run it. A documented command that fails on a clean machine is worse than a short help text.","steps":[{"name":"Paste one command's help","text":"Copy the usage block for the command you care about, not the entire manual for a huge CLI. Add one line about which example a new user needs."},{"name":"Mark unfinished flags","text":"Name any flag that should stay out of the examples. The rewriter will not advertise it."},{"name":"Paste the prompt","text":"You get three examples a person can copy, a short list of flags that matter, and the flags you hid."},{"name":"Replace the examples in the help or the README","text":"Put the examples above the flag dictionary. Run one of them with --dry-run if that flag exists, so the docs are not fiction."}],"demo":[{"second":0,"label":"The dump","detail":"ledger refund needs --order, optional --dry-run. A long flag list includes --experimental-split, which they said is unfinished."},{"second":8,"label":"Three examples","detail":"A dry run, a real refund with --order, and a json version. Each uses the binary name ledger."},{"second":16,"label":"Flags that matter","detail":"--order, --dry-run, --json. Timeout stays in the dictionary because it has a default, not in the first example."},{"second":24,"label":"Hidden","detail":"--experimental-split is listed under do-not-feature. No invented subcommand."}],"sampleInput":"$ ledger --help\nUsage: ledger <command> [flags]\nCommands:\n  refund     Refund an order\n  review     Weekly review from a dump\nFlags:\n  --help\n  --version\n  --json\n  --config string\n  --timeout duration (default 30s)\n  --dry-run\n  --endpoint string\n  --verbose\n  --no-color\n  --experimental-split\nI want examples for refund. A refund needs --order and an optional --dry-run.\n--experimental-split is unfinished. Do not feature it.\nThe real binary name is ledger.","prompt":"You rewrite CLI help into examples a person will copy. You do not invent flags.\n\nINPUTS\n- Help text for one command.\n- The example they want a new user to run.\n- Flags that must not be featured.\n\nRULES\n- Three examples, copy-pasteable, using the binary and command from the help text.\n- Every flag in an example must appear in the help text.\n- Do not feature a flag they banned.\n- If a required flag is obvious from the help, the first example includes it.\n- Do not invent a default, a subcommand, or an example that needs a secret. Use placeholders like ORDER_ID.\n- After the examples, list \"flags that matter\" (the ones you used) and \"leave in the dictionary\" (the rest).\n- If the help is too broad (many unrelated commands), ask them to paste one command and stop.\n\nOUTPUT\n## Examples\nThree fenced commands, each with a one-line caption.\n\n## Flags that matter\n## Leave in the dictionary\n## Not featured\nBanned flags, or \"None.\"","config":null}}