Topolearn

Learn Click

Composable command-line interfaces in Python with decorators

15 lessons · 3 hours · 4 levels · covers Click 8.5

Click is a Python package for building command-line tools by decorating functions: options, arguments, nested command groups, prompts, help pages and shell completion all come from declarations. It powers the CLIs of Flask, pip-tools, Black and many other projects. Learning it lets you turn scripts into polished, testable command-line applications quickly.

Sign in free to track progressOfficial docs ↗

Before you start

Click builds on these; the tree links to the exact lessons you need.

PythonEssentials level

How deep do you want to go?

1. EssentialsRead and write simple code, do the everyday basics4 lessons · 37 min in total
2. PracticalUse it productively at work, with the usual idioms9 lessons · 2 hours in total
3. AdvancedThe less common features, performance and trade-offs12 lessons · 2 hours in total
4. ExpertInternals and the edge cases experts know15 lessons · 3 hours in total

The Click tree

ClickYour first Click commandYour first ClickcommandOptionsOptionsArgumentsArgumentsOutput, styling and help textOutput, styling andhelp textParameter types and validationParameter types andvalidationCommand groups and subcommandsCommand groupsand subcommandsThe context and sharing stateThe context andsharing stateTesting CLIs with CliRunnerTesting CLIs withCliRunnerPrompts, confirmation and environment variablesPrompts,confirmation and e…Defining functionsDefining functionsModules and importsModules and importsTesting with pytest and unittestTesting with pytestand unittestPackaging with pyproject.tomlPackaging withpyproject.tomlClasses and instancesClasses andinstancesInheritance, super() and compositionInheritance, super()and compositionExceptions in depthExceptions in depth
Essentials and Practical shown (9 of 15 lessons); the full list is below. Click a lesson to read it.

All 15 lessons, in order

First commands

  1. Your first Click command · Essentials · 8 min

    Turn a function into a command-line program with @click.command and run it, getting --help for free.

  2. Options · Essentials · 11 min

    Add named options like --count 3 and boolean flags like --verbose with @click.option, including defaults and help.

  3. Arguments · Essentials · 9 min

    Declare positional arguments with @click.argument, including optional and variadic ones, and know when to prefer options.

  4. Output, styling and help text · Essentials · 9 min

    Print with echo and secho, add colour with style, and shape help output with docstrings, epilogs and metavars.

Parameters

  1. Parameter types and validation · Practical · 12 min

    Validate input with built-in types like Choice, IntRange, Path and File, so bad values fail with clear errors.

  2. Prompts, confirmation and environment variables · Practical · 10 min

    Fill values interactively with prompt=, confirm destructive actions, hide passwords and read defaults from environment variables.

  3. Custom types and callbacks · Advanced · 12 min

    Write ParamType subclasses for domain values and use callbacks and eager options for validation and early actions.

Groups and context

  1. Command groups and subcommands · Practical · 11 min

    Build git-style CLIs with @click.group and subcommands, including group options and command chaining.

  2. The context and sharing state · Practical · 11 min

    Use click.Context, @pass_context and ctx.obj to share configuration and resources between a group and its subcommands.

Testing and shipping

  1. Testing CLIs with CliRunner · Practical · 11 min

    Invoke commands in-process with click.testing.CliRunner and assert on output, exit codes and exceptions.

  2. Packaging a CLI with entry points · Advanced · 10 min

    Install your Click app as a real command with [project.scripts] in pyproject.toml, and structure the package for it.

  3. Shell completion · Advanced · 10 min

    Enable tab completion for bash, zsh, fish and PowerShell, and provide dynamic completions with shell_complete.

Advanced and internals

  1. Custom groups and lazy loading · Expert · 13 min

    Subclass click.Group and override list_commands and get_command for plugins, aliases and lazily imported subcommands.

  2. Exceptions, exit codes and standalone mode · Expert · 11 min

    Control error reporting and exit codes with ClickException, UsageError, Abort and standalone_mode.

  3. How Click parses: contexts and parameter order · Expert · 13 min

    Follow an invocation from make_context through parsing, parameter processing order, callbacks and invoke.