click

Project Overview

Click is a Python package for creating beautiful command line interfaces in a composable way with as little code as necessary. It stands for Command Line Interface Creation Kit, is highly configurable yet comes with sensible defaults, and aims to make writing command line tools quick and fun.

Write CLIs with decorators: arbitrary command nesting, automatic help pages, and lazy subcommand loading.

Key Features

• Composable commands: commands nest to any depth, keeping complex CLIs well organized
• Automatic help pages: help text is generated from function docs and parameter definitions
• Lazy subcommands: subcommands can be loaded on demand at runtime for faster startup
• Decorator based: @click.command and @click.option turn plain functions into commands
• Interactive prompts: options support prompts, asking the user when a value is missing
• Sensible defaults: good behavior out of the box while remaining highly configurable

Target Audience

• Python CLI tool developers
• Operations automation script authors
• Builders of multi-command tools
• Developers wrapping scripts as commands

Quick Start

1. Install:

pip install click

2. Define a command with decorators:

import click

@click.command()
@click.option('--count', default=1, help='Number of greetings.')
@click.option('--name', prompt='Your name', help='The person to greet.')
def hello(count, name):
    '''Simple program that greets NAME for a total of COUNT times.'''
    for _ in range(count):
        click.echo(f'Hello, {name}!')

if __name__ == '__main__':
    hello()

3. Run it:

python hello.py --count=3

Core Advantages

• Less code: declarative decorators produce a complete CLI in a few lines
• Predictable behavior: help pages and argument handling are generated, so users get started quickly
• Flexible composition: commands nest freely, letting small scripts grow into large tools

System Requirements

Notes

• Docstring is the docs: a command's docstring becomes its help page description, so write it clearly
• Interactive prompt: the example sets a prompt for --name, so the program pauses for input when the option is missing