Skip to main content
TemplateFREEโฑ๏ธ 15 minutes

CLI Tool Specification Template

A structured template for specifying CLI tool features, commands, flags, and output formats. Covers command hierarchy, argument validation, help text.

Updated 2026-03-05

Get this template

Every format is free. No account, no email required.

Frequently Asked Questions

How many subcommand levels should a CLI tool have?+

Limit nesting to two levels maximum (e.g., tool group command). Three or more levels make the tool harder to discover and type. If you find yourself needing a third level, consider flattening the hierarchy or splitting into separate tools. Most successful CLIs like git, docker, and kubectl stay at two levels.

Should flags use single-dash or double-dash prefixes?+

Use double-dash for full flag names (--verbose) and single-dash for single-character shortcuts (-v). This is the POSIX convention and what developers expect. Allow combining short flags (-vq for --verbose --quiet). Never use single-dash for multi-character flags.

When should a CLI output JSON versus plain text?+

Default to human-readable text for interactive use. Support --format json for scripts and automation. Some teams add --format yaml as well. The key rule is that JSON output should be stable. If you change the JSON schema, treat it as a breaking change and version your output format.

How do I handle authentication in a CLI?+

Store credentials in a dotfile in the user's home directory (e.g., ~/.toolrc/credentials). Support environment variables as overrides for CI/CD environments (TOOL_API_KEY). Never require the user to pass credentials as command-line arguments since those appear in shell history. The Technical PM Handbook covers security considerations for developer-facing tools.

Should I include a --dry-run flag for every command?+

Include --dry-run on every command that modifies state (deployments, deletions, configuration changes). It is not needed for read-only commands like list or status. The dry-run output should show exactly what would happen, not just "no changes made." ---

Explore More Templates

Browse our full library of PM templates, or generate a custom version with AI.