docopt — CLI Argument Parser from Help Messages

Introduction

docopt takes a different approach to CLI argument parsing: you write the help message first, and docopt parses it to build the argument parser automatically. This means your usage documentation is always in sync with your actual argument handling. The idea originated in Python and has been ported to over 20 programming languages, making it a universal pattern for CLI design.

What docopt Does

• Parses command-line arguments based on a POSIX-style usage message you write as a docstring
• Supports commands, positional arguments, required and optional flags, and repeating elements
• Returns a simple dictionary mapping argument names to their parsed values
• Validates user input against the usage pattern and prints help on mismatch
• Works across 20+ languages including Python, JavaScript, Ruby, Go, Rust, C, and Bash

Architecture Overview

docopt works in two phases. First, it parses the usage message string using a formal grammar that recognizes POSIX conventions: uppercase WORDS are positional args, --flags are options, [brackets] denote optional elements, and (parens) denote required groups. Second, it matches the actual argv against the parsed pattern tree, extracting values and setting boolean flags. The result is a flat dictionary. There is no code generation or class hierarchy involved, keeping the implementation under 500 lines in most language ports.

Self-Hosting & Configuration

• Install for your language: pip install docopt (Python), npm install docopt (JS), cargo add docopt (Rust)
• Write your usage message following POSIX conventions as a module docstring or string constant
• Call docopt(doc) with the usage string to get a dictionary of parsed arguments
• Use -- in your usage pattern to separate options from positional arguments
• Set version= to enable automatic --version flag handling

Key Features

• Usage message IS the parser: documentation and parsing logic never drift apart
• Zero boilerplate: no argument builder chains, decorators, or configuration objects
• Language-agnostic pattern implemented in 20+ languages with identical behavior
• Supports complex CLI grammars including subcommands, mutually exclusive groups, and repeating args
• Tiny implementation (under 500 lines in Python) with no external dependencies

Comparison with Similar Tools

• argparse — Python stdlib; requires imperative code to define each argument; docopt uses a declarative usage string
• Click — decorator-based Python CLI framework with more features (prompts, colors); docopt is simpler and language-agnostic
• Typer — builds CLIs from type hints; docopt builds them from documentation strings
• Cobra — Go CLI framework with code generation; docopt's Go port uses the same doc-first approach
• Clap — Rust's dominant CLI parser with derive macros; docopt's Rust port trades features for simplicity

FAQ

Q: Is docopt still maintained? A: The original Python implementation is stable and feature-complete. Community ports in other languages are maintained independently.

Q: Can I use subcommands with docopt? A: Yes. List subcommands in your usage pattern and docopt will set the matching command to True in the result dictionary.

Q: How does docopt handle type conversion? A: docopt returns all values as strings (or booleans for flags). You handle conversion yourself, which keeps the library focused on parsing.

Q: What happens if the user provides invalid arguments? A: docopt prints the usage message and exits with a non-zero status code, following standard CLI conventions.

Sources

• https://github.com/docopt/docopt
• http://docopt.org/