base-cli

base-cli is a small, consumer-neutral Python framework for writing professional command-line applications. It gives commands a consistent lifecycle, context, logging, cleanup, configuration, and test boundary while leaving application policy in the consuming project.

Quick start

Install the package:

python -m pip install base-cli

Create a command:

from __future__ import annotations

import base_cli


app = base_cli.App(name="hello", version="0.1.0")


@app.command()
@base_cli.option("--name", default="world", show_default=True)
def hello(ctx: base_cli.Context, name: str) -> int:
    ctx.log.info("greeting %s", name)
    print(f"Hello, {name}!")
    return base_cli.ExitCode.SUCCESS


if __name__ == "__main__":
    raise SystemExit(base_cli.run_app(app))

Run it with:

python hello.py --name Ada

The command receives a context with structured logging, per-run paths, configuration, environment metadata, and deterministic cleanup. The same lifecycle can be attached to an existing Click tree or an optional Typer application.

Choose a path

• Start with the adopter readiness guide for a production evaluation.
• Read API stability and the migration guide before upgrading across a compatibility boundary.
• Follow consumer profiles when your application owns project discovery or configuration policy.
• Use the Typer adapter to bring an existing Typer command tree under the same lifecycle.
• Review the JSON contracts and output contracts before building automation around command output.

Design principles

base-cli is intentionally thin: Click owns parsing and command execution, while the framework supplies reusable lifecycle behavior. It avoids import-time filesystem writes, keeps logs on stderr, preserves application-owned state, and treats optional integrations as explicit extras.

See the repository README for the full API overview, reference applications, and installation examples.