CLI Tool README Template

Crafting a CLI Tool README

Command-line tools have unique documentation needs compared to libraries. Users need to understand installation methods, command syntax, available flags, and configuration options. The README should serve as both a quick-start guide and a reference manual.

Installation Methods

CLI tools typically offer multiple installation paths:

# Global install (recommended)
npm install -g my-cli

# Run without installing
npx my-cli

# Homebrew (if applicable)
brew install my-cli

Show the global install first since CLI tools are typically used as system-wide commands, unlike libraries which are project dependencies.

Command Syntax

Document the primary commands with a clear syntax pattern:

my-cli <command> [options]

Commands:
  init          Initialize a new project
  build         Build the project
  deploy        Deploy to production
  config        Manage configuration

Options:
  -v, --version    Show version number
  -h, --help       Show help
  --verbose        Enable verbose output
  --config <path>  Path to config file

Practical Examples

CLI READMEs benefit enormously from real-world examples. Show common workflows:

# Create a new project
my-cli init my-app --template react

# Build with custom output
my-cli build --output ./dist --minify

# Deploy to staging
my-cli deploy --env staging --dry-run

Configuration File

If your tool supports configuration files, document the format and available options:

{
  "output": "./dist",
  "minify": true,
  "plugins": ["plugin-a", "plugin-b"]
}

Exit Codes

Document exit codes for scripting and CI integration:

• 0 - Success
• 1 - General error
• 2 - Invalid arguments