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.