CLI Tool README Template
Command-line tools have specific README requirements that differ from libraries and web APIs. CLI users want to know three things immediately: how to install it on their operating system, what the most common command is, and what the output looks like. The entire decision to adopt a CLI tool often rests on seeing a clean, compelling example of the tool in action before any further reading.
Installation instructions for CLI tools must cover multiple installation methods and operating systems. List them in order of user preference: package manager installations (Homebrew on macOS, apt/yum on Linux, Scoop/winget on Windows) are preferable to manual binary downloads because they handle updates. If you publish to npm and the tool is JavaScript-based, show the global npm install command. For tools distributed as binaries, provide direct download links and checksums for each platform.
The command reference is the core of a CLI README. Use a consistent format: command name, description, flags with their types and defaults, and at least one example per command. A flag reference table with columns for short form, long form, default, and description is more scannable than paragraphs of prose. Consider asciinema recordings or screenshots of the tool running for visually demonstrating complex interactions.
Shell completion is a significant usability feature that dramatically improves the developer experience. Document how to install completion scripts for bash, zsh, and fish if your tool supports them. Many CLI READMEs omit this entirely, leaving users to discover it only by running --help.
Exit codes are critical for CLI tools used in shell scripts and CI pipelines. Document the exit code conventions: 0 for success, 1 for general errors, and any tool-specific codes for specific failure modes. Shell script authors need to know what exit codes to handle.
Configuration file support deserves its own section if your tool reads from a configuration file (like .toolrc or tool.config.json). Show the full configuration schema with all keys, their types, their defaults, and what each controls. Configuration documentation is often discovered only when users need to customize behavior beyond the default, so it does not need to be prominent but must be complete.
Template Preview
{"projectType":"cli","language":"Go","includesInstallation":true,"includesCommandReference":true,"includesFlags":true,"includesShellCompletion":true,"includesExitCodes":true,"license":"MIT"}Customize this template with your own details using the free generator:
▸Open in GeneratorFAQ
- How do I show terminal output in my README?
- Use fenced code blocks with the bash or text language hint. For realistic terminal output, prepend the prompt ($ or ❯) to commands and show the actual output directly below without any prompt. For multi-step interactions, show each command and its output in sequence. Avoid cropping output with "..." — if the output is too long for the README, show a representative subset and note that actual output may vary.
- Should I use animated GIFs or asciinema recordings?
- Both work well. Animated GIFs are universally supported but can be large and cannot be paused or copied from. Asciinema recordings are lightweight and allow copy-paste but require JavaScript. For a quick 5-second demo of the core functionality, a GIF is ideal. For complex multi-step workflows, an asciinema recording is better. Store GIFs in the repository under docs/assets/ and reference them with a relative path.
- How do I document breaking changes in a CLI tool README?
- Maintain a CHANGELOG.md and link to it prominently from the README. In the README itself, keep a "Migration Guide" or "Breaking Changes" section for the most recent major version only — older migration notes belong in the CHANGELOG. Version bump your tool following semver: major for breaking command signature changes, minor for new commands, and patch for bug fixes.