System Type: CLI Tool & Developer SDK

Patterns, failure modes, and anti-patterns for command-line tools and developer-facing libraries.

Command Structure Patterns

Subcommand Trees (git-style)

What it is. Top-level command dispatches to subcommands, each with its own flags and arguments. tool <subcommand> [flags] [args]. The dominant pattern for non-trivial CLIs. When to use. Tools with more than ~5 distinct operations. When operations have different flag sets. When you want discoverability — tool help lists all subcommands. When to avoid. Single-purpose tools that do one thing (e.g., curl, jq). Adding subcommands to a tool that does one thing well makes it do many things poorly. Nesting depth. Two levels (tool resource action) is the practical limit. Three levels (tool group resource action) works if the grouping is obvious (e.g., kubectl get pods). Four levels means your CLI needs a redesign.

Flag Conventions

POSIX short flags. Single dash, single letter: -v, -f. Combinable: -vvv for verbosity levels, -rf for multiple flags. Every short flag should have a long equivalent. GNU long flags. Double dash, full words: --verbose, --output-format. Self-documenting. Use hyphens, not underscores. Boolean flags. --color enables, --no-color disables. Pick a sensible default and provide the negation. Don't require --color=true. Value flags. --output json or --output=json. Support both forms. Be consistent across all flags. The -- separator. Everything after -- is a positional argument, not a flag. Mandatory for tools that accept arbitrary user input — without it, tool delete --force is ambiguous (is --force a flag or an argument?).

Positional Arguments vs. Flags

Positional args are for the primary noun — the thing being operated on. tool build ./src, tool deploy production. One or two positional args maximum. After that, you need flags. Flags are for everything that modifies behavior. If the user could reasonably forget to provide it and get a useful default, it's a flag, not a positional arg. Rule of thumb. If you're reading the help text to remember which positional arg is which, they should be flags.

Global vs. Local Flags

Global flags apply to every subcommand: --verbose, --config, --output-format, --no-color. Define them once at the root. They should be few and genuinely universal. Local flags belong to a specific subcommand. Don't pollute the global namespace with flags only one subcommand uses.

Interactive Prompts vs. Flags

Interactive prompts are for first-run setup, destructive confirmations, and guided workflows (tool init). Always provide a flag equivalent (--yes, --name=foo) so scripts can bypass prompts. TTY detection. If stdin is not a TTY, never prompt. Fail with an actionable error telling the user which flag to pass. A CI pipeline hanging on a prompt is a production incident.

stdin/stdout/stderr Discipline

stdout is for program output — the data the user asked for. It must be parseable. If someone pipes your output, only the data should flow through. stderr is for human messages — progress indicators, warnings, debug info, error messages. Everything that isn't the requested data. stdin is for data input. Accept - as a filename to mean stdin. Support piping: cat file | tool process and tool process < file. The test. tool list | wc -l should return a correct count. If your progress spinner or status message contaminates stdout, you've broken the Unix contract.

Configuration Layering

The Hierarchy

Highest precedence wins. The standard order:

1. Command-line flags. Always win. The user is explicitly telling you what to do right now.
2. Environment variables. Useful for CI, containers, and temporary overrides. Convention: TOOLNAME_FLAGNAME (e.g., GIT_AUTHOR_NAME).

…