Content-driven handbook for Python CLI teams

Python CLI Toolcraft

A practical handbook for building, testing, packaging, and shipping production-ready Python command-line applications — 82 in-depth guides across three tracks.

toolcraft --ship

$ uv init cli-tool
# create a reliable package layout
$ typer run app.py -- --help
# validate commands before release
$ python -m pytest
# ship predictable terminal software

Browse the knowledge base

Three core tracks for modern Python CLI work

Start with the track that matches the problem in front of you — every guide links up to its section and sideways to related pages.

Topic track

Project Setup & Dependency Management

Build a dependable foundation with packaging, dependency resolution, versioning, virtual environments, and distribution workflows for Python CLI projects.

pyproject.toml & entry pointsuv, Poetry & pipxWheels, releases & standalone binaries

Explore project setup

Topic track

Modern Python CLI Frameworks & Architecture

Choose frameworks, structure command trees, and design extensible, fast-starting command-line systems that can scale with your product or team.

argparse, Typer & ClickMulti-command structureTesting, plugins & startup speed

Explore architecture

Topic track

Advanced Input Parsing & User Experience

Improve validation, config loading, error handling, logging, and terminal rendering so Python CLIs stay predictable for both humans and automation.

Validation & config precedenceErrors, exit codes & loggingPipes, help output & completion

Explore input and UX

New in this release

Four sections added this quarter

Testing, pipes, help output and standalone distribution — the parts of a CLI people reach for once the tool has users.

Testing Python CLI applications

Invoke commands in-process with CliRunner, isolate the filesystem and network, and keep a suite fast enough to run before every push.

Working with stdin, stdout and pipes

Read piped input, keep stdout free of narration, emit stable JSON, and survive a downstream command that exits early.

CLI help output and documentation

Write help people can scan, put runnable examples in an epilog, generate man pages, and deprecate flags without breaking scripts.

Distributing CLIs as standalone binaries

Ship to users without Python: PyInstaller, shiv zipapps, a cross-platform release matrix, and Homebrew or Scoop packaging.

How to use the handbook

Three ways in

You have a problem right now

Go straight to the guide. Every page opens with the answer before the explanation, so the first screen is usually enough to get unblocked.

You are starting a tool

Follow the recommended path on each track overview, in order. It front-loads the decisions that are expensive to reverse: layout, locking, and the shape of the command tree.

You are hardening something

Run the eight-invocation audit at the end of the input and terminal UX overview. Each failure points at the guide that fixes it.