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 — more than 180 in-depth guides across four 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

Four 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

Topic track

CLI Runtime & Systems Integration

Run subprocesses safely, write files atomically, call HTTP APIs, add concurrency, protect credentials and keep long-running commands healthy.

Subprocesses, files & HTTP APIsConcurrency, async & rate limitsSecrets, signals & scheduling

Explore runtime and integration

New in this release

Six sections added this quarter

Subprocesses, HTTP APIs, secrets, CI/CD, interface design and terminal UIs — what a CLI needs once it works with other systems and other people.

Running subprocesses from Python CLIs

Call git and other tools safely: argument lists instead of shells, timeouts, streamed output and exit codes that mean something.

Calling HTTP APIs from Python CLIs

Build an httpx client with retries and backoff, paginate results, download with progress and log in with the OAuth device flow.

Secrets and credentials in Python CLIs

Keep tokens in the OS keyring, prompt without echo, support several profiles and redact secrets from every log line.

CI/CD pipelines for Python CLIs

Test across Python versions, smoke-test the built wheel, release from git tags and publish to PyPI with trusted publishing.

Designing CLI interfaces and conventions

Consistent names, dry runs for destructive commands, global versus per-command options and the POSIX conventions users expect.

Building terminal UIs with Textual

Decide when a command should become a full-screen app, build one with Textual, and test it headlessly with Pilot.

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.