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 230 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 & pipxReleases, binaries & supply-chain security

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, Click & alternativesMulti-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, output formats & 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, local state & SQLiteSecrets, services & update checks

Explore runtime and integration

New in this release

Five new topics and a hundred new guides

Output formats, alternative frameworks, local state, update checks and supply-chain security — plus deeper guides in every existing topic, from systemd services to structured concurrency.

Output formats for data CLIs

One --format flag for tables, JSON and CSV, field selection, format-string templates and exports that scripts can trust.

Alternative Python CLI frameworks

Cyclopts, Python Fire, docopt-ng and Cleo compared with Typer and Click — what each does well and when to choose it.

Local state and SQLite in Python CLIs

Keep state in SQLite with schema migrations, cache HTTP responses on disk and record a queryable history of runs.

Update checks and self-updating CLIs

Check PyPI for new releases without slowing anyone down, show polite notices, upgrade pipx and uv installs, and ask before telemetry.

Securing a Python CLI supply chain

Audit dependencies, pin with hashes, publish attestations users can verify and generate an SBOM for every release.

Running a CLI as a systemd service

Turn an agent command into a supervised service with readiness, a watchdog, config reloads on SIGHUP and structured journal logs.

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.