---
name: cli-tool-creator
description: "Designs a command-line tool end to end: the commands, flags, output formats, error behaviour and help text, before anyone codes it. Use when a new command-line tool needs its commands, flags, output formats and error messages designed before implementation starts. Do not use for writing the implementation or parsing an existing tool's arguments. Related topics: coding, productivity."
---

# CLI Tool Creator

Designs a command-line tool end to end: the commands, flags, output formats, error behaviour and help text, before anyone codes it.

## When to use

Use this skill when a new command-line tool needs its commands, flags, output formats and error messages designed before implementation starts. Do not use it for writing the implementation or parsing an existing tool's arguments.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Rank the typical tasks and make the most frequent one reachable with the fewest keystrokes.
3. Define the command tree with arguments, flags, defaults and one example each, using consistent names throughout.
4. Specify human and machine output, exit codes, and the exact wording pattern for error messages.
5. State the configuration precedence across flags, environment and file for every setting.
6. Write the real help text for the root and one sub-command and list what version one leaves out.

## Inputs

- **Tool purpose** (longer free text)
- **Tool name** (free text, e.g. "Short lowercase name")
- **Typical tasks** (longer free text)
- **Implementation language** (choose one: Node, Python, Go, Rust, Bash)
- **Output consumers** (choose any: Humans, Scripts, CI pipelines)
- **Config sources** (choose any: Flags, Environment variables, Config file)

## Output

A design document with the command tree, a flag table, output and exit code rules, error message patterns, config precedence, sample help text and a not-in-v1 list.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### CLI Tool Creator

Design a command-line tool.

- Tool purpose: {{Tool purpose}}
- Tool name: {{Tool name}}
- Typical tasks: {{Typical tasks}}
- Implementation language: {{Implementation language}}
- Output consumers: {{Output consumers}}
- Config sources: {{Config sources}}

Start from the typical tasks and make the most common one the shortest to type. Define the command tree with verbs for actions and nouns for things, and keep flag names consistent across commands. For every command give its arguments, flags with defaults, and an example. Specify output: readable text by default, a JSON flag for scripts, no colour or spinners when output is piped. Define exit codes, with zero for success and distinct non-zero codes for usage errors and runtime failures, and write each error message to say what failed, why and what to try. Set the config precedence: flags over environment over file over defaults. Write the exact help text for the top-level command and one sub-command. Finish with a short list of things deliberately left out of the first version.

## Pitfalls

- Inventing a new flag name per command, so users cannot guess one from another.
- Printing progress bars and colour into a pipe, which corrupts the output scripts read.
- Returning exit code 0 on partial failure, so CI reports a green build over a broken result.