Python CLI Library Selection¶

Use this reference when choosing libraries for a new Python CLI or deciding whether an existing stack still fits. Choose each layer independently: a command parser, terminal renderer, terminal UI, settings model, HTTP client, authentication implementation, test runner, and package manager solve different problems.

Default Stack¶

For a new typed application CLI, start with:

Add Textual only when the product needs a persistent, event-driven terminal interface. It complements a command parser; it does not replace the scriptable command surface.

This is a starting point, not a mandate. Preserve a sound existing stack unless a requirement exposes a concrete limitation.

Choose The Command Framework¶

Use Cyclopts by default for a new typed application CLI¶

Cyclopts derives commands and parameters from Python function signatures and supports built-in and user-defined types, including unions, literals, dataclasses, Pydantic models, and attrs classes. It can derive help from docstrings and provides converters, validators, nested commands, lazy loading, configuration sources, documentation integration, and testing guidance.

Choose Cyclopts when:

• Modern type annotations should be the primary command schema.
• Commands accept structured dataclasses or validation models.
• Rich unions, literals, nested structures, or reusable parameter groups matter.
• The project values concise declarations and generated documentation.
• A newer and smaller ecosystem is an acceptable tradeoff.

Before committing, prototype the hardest command signature, help page, validation error, completion behavior, and test invocation. Do not evaluate a framework only on a one-command example.

Use Typer for the mainstream type-driven choice¶

Typer also derives CLI arguments and options from Python type hints and provides automatic help, shell completion, nested command groups, Rich-formatted output, packaging guidance, and test helpers. It is a strong choice when contributor familiarity, established examples, and ecosystem recognition matter more than Cyclopts' broader type model.

Since Typer 0.26.0, Typer vendors Click rather than depending on the external Click package. Do not assume an arbitrary Click extension or subclass will integrate with modern Typer; verify that requirement against the installed Typer release.

Choose Typer when:

• The team already knows Typer or follows the FastAPI ecosystem.
• The command types fit Typer's supported parameter model.
• A familiar, established type-driven framework lowers contributor cost.
• Existing Typer conventions or integrations outweigh framework-switching benefits.

Use Click when explicit control is the requirement¶

Click models commands, groups, contexts, parameters, types, and invocation explicitly. It supports arbitrary command nesting, lazy subcommand loading, custom parameter types, extension APIs, testing utilities, and a mature plugin ecosystem.

Choose Click when:

• The CLI is itself a framework or plugin host.
• Commands must be discovered or loaded lazily.
• Parsing, context propagation, invocation, or help behavior needs unusual customization.
• Existing Click extensions are a hard dependency.
• Explicit declarations are preferable to inference from application types.

Do not choose Click merely because it is mature. For ordinary application commands, the extra parser-level detail may duplicate function types, defaults, validation, and documentation.

Use argparse when dependency constraints dominate¶

argparse is the standard-library parser and supports subcommands, generated help, custom actions and types, argument files, and parser-level error handling. Python 3.14 added colored help and suggest_on_error, making its default experience more capable than older comparisons imply.

Choose argparse when:

• The tool must remain standard-library-only.
• It is a small utility with a stable and modest command surface.
• Conservative deployment environments value availability over declaration ergonomics.
• Adding a runtime dependency has a real operational cost.

For a substantial typed application, account for the duplication between parser declarations and the application's function signatures, models, defaults, validation, and help text.

Use Fire for exposure, not deliberate public design¶

Python Fire generates a CLI from functions, classes, modules, mappings, and other Python objects. This is useful for developer tools, debugging, exploration, and rapidly exposing an internal Python API.

Avoid Fire as the default for a stable public CLI. Exposing the Python object model couples command names, arguments, and behavior to implementation details instead of treating the CLI as a deliberately designed compatibility surface.

Framework Decision Table¶

When Cyclopts and Typer both fit, build the same representative vertical slice in each. Include the most complex parameter model, nested command registration, configuration injection, help output, validation failure, shell completion, and command test. Select from that evidence rather than syntax preference.

Keep Complementary Libraries In Their Layer¶

Rich is presentation, not parsing¶

Use Rich behind a renderer abstraction for human-readable tables, progress, status displays, syntax, and styled errors. Keep structured output on a separate serialization path so --output json never contains decoration, progress, or terminal control codes.

Typer includes Rich as a dependency and uses it for formatted errors. Cyclopts can also produce Rich-oriented help and errors. This does not remove the need for an application-owned output boundary.

Textual is an optional interactive mode¶

Use Textual when users need a persistent screen, navigation, reactive widgets, keyboard actions, or live dashboards. Keep ordinary parser commands for automation and direct operations:

mycli projects list       -> scriptable command
mycli interactive         -> Textual application
             both -> application services -> API client

The command and TUI adapters should call the same application services. Do not embed API and domain behavior separately in Textual event handlers.

Supporting Stack Decisions¶

Configuration and models¶

Use dataclasses when configuration is small, already parsed, and needs no source orchestration. Use Pydantic for structured request, response, configuration, or command models that benefit from validation and serialization. Use Pydantic Settings when environment variables, dotenv files, secret files, or custom settings sources participate in explicit precedence.

Do not pass framework parameter objects into application services. Convert parser output into ordinary typed values or application models at the command boundary.

HTTP¶

Use HTTPX2 for new API clients. It is the actively developed continuation of HTTPX and supports synchronous and asynchronous clients, explicit timeouts, streaming, custom authentication, and mock transports. Authlib 1.8+ integrates with HTTPX2 directly. Reuse a client with explicit timeouts rather than calling top-level request functions throughout resource methods.

Preserve HTTPX in a sound existing client until its dependencies, type checks, and transport tests are ready to migrate. Do not use HTTPX2's process-wide import alias from reusable library code, and do not keep HTTPX and HTTPX2 as permanent parallel transports without a concrete compatibility requirement.

Use aiohttp when the project already standardizes on its async client, depends on its streaming or WebSocket behavior, or has measured requirements that justify a different transport. Do not introduce both HTTPX2 and aiohttp without a clear ownership boundary.

Authentication¶

Use Authlib 1.8+ for OAuth protocol behavior rather than implementing grants, PKCE, token parsing, and refresh directly. Keep it behind an authentication abstraction. For OAuth-enabled installed applications, follow OAuth 2.0 for installed CLI clients.

Use keyring to access operating-system credential stores when the deployment environment provides one. Treat headless secret storage as an explicit deployment decision rather than silently falling back to plaintext configuration.

Testing and packaging¶

Use pytest for application and command tests. Combine framework-level invocation helpers with subprocess tests of the installed console entry point; a runner helper alone does not verify packaging or startup behavior.

Use uv for dependency management, lockfiles, isolated tool execution, and project commands when the repository adopts uv. Declare the CLI through a [project.scripts] entry point in pyproject.toml so installation, tests, and users invoke the same bootstrap path.

Architecture Rule¶

Do not couple application behavior to the chosen CLI framework:

Cyclopts / Typer / Click / argparse
                 |
                 v
        thin command adapters
                 |
                 v
       application services
                 |
                 v
            API client

Command functions should parse or receive values, call an application service, and hand the result to a renderer. Keep API calls, authentication, retries, and domain decisions outside parser decorators and callbacks. This makes framework-specific tests small and keeps a future parser migration bounded.

Selection Checklist¶

1. Identify the minimum supported Python version and dependency constraints.
2. Model the hardest real command, not the smallest demonstration command.
3. Decide whether type annotations or explicit parser objects should own the command schema.
4. Check complex types, nested commands, lazy loading, plugins, completion, help, validation, and test support against actual requirements.
5. Separate parsing from Rich presentation and optional Textual interaction.
6. Select configuration, HTTP, authentication, testing, and packaging libraries independently.
7. Prototype ambiguous framework choices with the same vertical slice.
8. Pin compatible versions and verify behavior against installed-library documentation before implementation.
9. Keep application services free of CLI-framework types.
10. Preserve stable stdout, stderr, and exit-status contracts regardless of library defaults.