When this skill is activated, always start your first response with the 🧢 emoji.
CLI Design
CLI design is the practice of building command-line tools that are intuitive,
composable, and self-documenting. A well-designed CLI follows the principle of
least surprise - flags behave like users expect, help text answers questions
before they are asked, and errors guide toward resolution rather than dead ends.
This skill covers argument parsing, help text conventions, interactive prompts,
configuration file hierarchies, and distribution strategies across Node.js,
Python, Go, and Rust ecosystems.
When to use this skill
Trigger this skill when the user:
Wants to build a new CLI tool or add subcommands to an existing one
Needs to parse arguments, flags, options, or positional parameters
Asks about help text formatting, usage strings, or man pages
Wants to add interactive prompts, confirmations, or selection menus
Needs to manage config files (dotfiles, rc files, XDG directories)
Asks about distributing a CLI via npm, pip, cargo, brew, or standalone binary
Wants to add shell completions (bash, zsh, fish)
Needs to handle stdin/stdout piping and exit codes correctly
Do NOT trigger this skill for:
GUI application design or web UI - use frontend or ultimate-ui skills
Shell scripting syntax questions unrelated to building a distributable CLI tool
Key principles
Predictability over cleverness - Follow POSIX conventions: single-dash
short flags (-v), double-dash long flags (--verbose), -- to end flag
parsing. Users should never have to guess how your flags work.
Self-documenting by default - Every command must have a --help that
shows usage, all flags with descriptions, and at least one example. If a
user needs to read external docs to run a command, the help text has failed.
Fail loudly, recover gracefully - Print errors to stderr, not stdout.
Use non-zero exit codes for failures. Include the failed input and a
suggested fix in every error message. Never fail silently.
Composability - Respect the Unix philosophy: accept stdin, produce
clean stdout, use stderr for diagnostics. Support --json or
--output=json for machine-readable output so other tools can pipe it.
Progressive disclosure - Show the simplest usage first. Hide advanced
flags behind subgroups or separate commands. New
users see 5 flags; power users discover 30.
--help
help <topic>
Core concepts
Argument taxonomy
CLI arguments fall into four categories that every parser must handle:
Type
Example
Notes
Subcommand
git commit
Verb that selects behavior
Positional
cp source dest
Order-dependent, unnamed
Flag (boolean)
--verbose, -v
Presence toggles a setting
Option (valued)
--output file.txt, -o file.txt
Key-value pair
Short flags can be combined: -abc equals -a -b -c. Options consume the
next token or use =: --out=file or --out file.
Config hierarchy
CLIs should load configuration from multiple sources, with later sources
overriding earlier ones:
1. Built-in defaults (hardcoded)
2. System config (/etc/<tool>/config)
3. User config (~/.config/<tool>/config or ~/.<tool>rc)
4. Project config (./<tool>.config.json or ./<tool>rc)
5. Environment vars (TOOL_OPTION=value)
6. CLI flags (--option value)
Exit codes
Code
Meaning
0
Success
1
General error
2
Misuse of command (bad flags, missing args)
126
Command found but not executable
127
Command not found
128+N
Killed by signal N (e.g. 130 = Ctrl+C / SIGINT)
Common tasks
1. Parse arguments with Node.js (Commander.js)
Define commands declaratively and let Commander handle help generation.
import { Command } from'commander';
const program = newCommand();
program
.name('mytool')
.description('A CLI that does useful things')
.version('1.0.0');
program
.command('deploy')
.description('Deploy the application to a target environment')
.argument('<environment>', 'target environment (staging, production)')
.option('-d, --dry-run', 'show what would happen without deploying')
.option('-t, --tag <tag>', 'docker image tag to deploy', 'latest')
.option('--timeout <ms>', 'deploy timeout in milliseconds', '30000')
.action((environment, options) => {
if (options.dryRun) {
console.log(`Would deploy ${options.tag} to ${environment}`);
return;
}
deploy(environment, options.tag, parseInt(options.timeout, 10));
});
program.parse();
2. Parse arguments with Python (click)
Click uses decorators for commands and handles type conversion, help
generation, and shell completions out of the box.
import click
@click.group()@click.version_option("1.0.0")defcli():
"""A CLI that does useful things."""pass@cli.command()@click.argument("environment", type=click.Choice(["staging", "production"]))@click.option("--dry-run", "-d", is_flag=True, help="Show what would happen.")@click.option("--tag", "-t", default="latest", help="Docker image tag.")@click.option("--timeout", default=30000, type=int, help="Timeout in ms.")defdeploy(environment, dry_run, tag, timeout):
"""Deploy the application to a target environment."""if dry_run:
click.echo(f"Would deploy {tag} to {environment}")
return
do_deploy(environment, tag, timeout)
if __name__ == "__main__":
cli()
3. Add interactive prompts
Use prompts for destructive actions or first-time setup. Never force
interactivity - always allow --yes / -y to skip prompts for scripting.
Always check process.stdout.isTTY before showing prompts. If the output
is piped or running in CI, fall back to defaults or error with a clear
message about which flags to pass.
4. Manage configuration files
Use cosmiconfig (Node.js) or similar to support multiple config formats.
Follow this template for every command's help output:
Usage: mytool deploy [options] <environment>
Deploy the application to a target environment.
Arguments:
environment target environment (staging, production)
Options:
-d, --dry-run show what would happen without deploying
-t, --tag <tag> docker image tag to deploy (default: "latest")
--timeout <ms> deploy timeout in milliseconds (default: "30000")
-h, --help display help for command
Examples:
$ mytool deploy staging
$ mytool deploy production --tag v2.1.0 --dry-run
Rules: show Usage: first with <required> and [optional] args. One-line
description. Group options logically with --help and --version last.
Always include 2-3 real examples at the bottom.
6. Handle stdin/stdout piping
Support stdin when no file argument is given. This makes the tool composable.
import { createReadStream } from'fs';
import { stdin as processStdin } from'process';
functiongetInputStream(filePath?: string): NodeJS.ReadableStream {
if (filePath) returncreateReadStream(filePath);
if (!process.stdin.isTTY) return processStdin;
console.error('Error: No input. Provide a file or pipe stdin.');
console.error(' mytool process <file>');
console.error(' cat file.txt | mytool process');
process.exit(2);
}
functionoutput(data: unknown, json: boolean) {
if (json) {
process.stdout.write(JSON.stringify(data) + '\n');
} else {
console.log(formatHuman(data));
}
}
7. Distribute the CLI
Node.js (npm) - set bin in package.json, ensure shebang #!/usr/bin/env node:
Breaks piping - error text contaminates data stream
Use console.error() or sys.stderr.write()
Exit code 0 on failure
Breaks && chaining and CI pipelines
Always process.exit(1) or sys.exit(1) on error
Requiring interactivity
Breaks CI, cron jobs, and scripting
Accept all inputs as flags; prompt only when TTY + flag missing
No --help on subcommands
Users cannot discover options
Every command and subcommand gets --help
Inconsistent flag naming
--dry-run vs --dryRun vs --dry_run
Pick kebab-case for flags, be consistent everywhere
Giant monolithic help text
Overwhelms users, hides important flags
Use subcommand groups; hide advanced flags in extended help
Non-standard flag syntax
/flag or +flag or flag:value
Stick to POSIX: -f, --flag, --flag=value
Swallowing errors silently
User has no idea something failed
Print error to stderr with context and suggested fix
No --version flag
Users cannot report which version they run
Always add --version to the root command
Gotchas
Interactive prompts in CI/scripts - A confirm prompt that blocks waiting for user input will hang a CI job indefinitely with no error message. Always check process.stdin.isTTY (or equivalent) before prompting, and provide a --yes / -y flag that skips all confirmations.
Exit code 0 on partial failure - A command that processes 10 files but fails on 2 and still exits 0 breaks && chaining and CI pipelines silently. Track failures explicitly and exit non-zero when any operation failed, even if some succeeded.
Flag name inconsistency across subcommands - Having --dry-run on deploy but --dryRun on migrate creates a mental tax for users. Establish naming conventions (kebab-case) at project start and enforce them in every subcommand - inconsistency compounds with every new feature.
Node.js shebang missing or wrong - Distributing a Node CLI without #!/usr/bin/env node as the first line means users must run node mytool instead of mytool, and npm's bin linking won't work correctly. Always set the shebang and make the file executable (chmod +x).
Swallowing parser errors - Argument parsers like Commander.js call process.exit(1) on invalid args by default, but some configurations catch and suppress these errors. An invalid flag that silently falls back to defaults is extremely confusing. Ensure validation errors always produce a clear message to stderr and a non-zero exit code.
References
For detailed patterns on specific CLI sub-domains, read the relevant file
from the references/ folder:
references/argument-parsing-patterns.md - advanced parsing patterns
including variadic args, mutually exclusive flags, coercion, and validation
across Node.js, Python, Go, and Rust
references/config-file-patterns.md - config file formats, XDG Base
Directory spec, schema validation, migration strategies, and environment
variable conventions
Only load a references file if the current task requires it - they are
long and will consume context.
Companion check
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
