base-cli-demo

Reference consumer and learning application for the base-cli Python framework.

This repository contains Northstar, a small offline operational CLI. It is designed to show how an application embeds Base-CLI while keeping its own command tree, domain policy, and local data model.

Northstar does not require Base, Docker, cloud credentials, or network access after its dependencies are installed.

Quick start

From a fresh checkout:

$ python3 -m venv .venv
. .venv/bin/activate
$ python -m pip install .
$ northstar --help
$ northstar --quiet status

The default environment is dev. Select another fixture environment with the framework lifecycle option:

$ northstar --quiet --environment staging status
$ northstar --quiet --environment dev status --format json
$ northstar --quiet --environment dev release plan --version 2.5.0
$ northstar --quiet --environment dev --dry-run release reconcile --version 2.5.0 --format json

Base-CLI also provides the optional versioned lifecycle envelope:

$ northstar --quiet --environment dev --json status --format json

For a guided five-minute walkthrough with expected output and the framework boundary explained beside each scenario, see the scenario-driven learning path.

What this demonstrates

• northstar status reads consumer-owned, deterministic service fixtures.
• northstar release plan is a nested command that produces a machine-readable release plan.
• northstar release reconcile uses the Base-CLI dry-run lifecycle boundary and explicitly reports that the demo performs no external changes.
• --environment, --quiet, --debug, --config, --keep-temp, and --log-file are lifecycle options supplied by Base-CLI.
• --format is a consumer-owned option that delegates rendering to the public Base-CLI output API.
• The --json option wraps command output in Base-CLI's versioned success or error envelope.
• The lifecycle safety guide shows dry-run safety, structured errors, redacted diagnostics, temporary paths, and cleanup.
• The released-package compatibility guide explains the supported Base-CLI range and the installed-wheel CI gate.
• The optional integration scenarios show Typer, Rich, and OpenTelemetry without making them core dependencies.
• The release process covers reproducible wheel and source-distribution validation separately from Base-CLI versioning.

Framework boundary

The application uses only the public import base_cli facade. Base-CLI owns the invocation lifecycle, context, logging, runtime paths, cleanup, and structured output. Northstar owns the Click command tree, service fixture schema, release planning policy, and domain-facing messages.

The generic consumer profile is explicit in src/base_cli_demo/cli.py. The demo does not inherit Base-specific manifest, project, history, or cache conventions.

Consumer-owned configuration

Northstar keeps the generic Base-CLI profile and opts into one small consumer-owned policy: an explicit JSON config can filter services by owner and set the default release target. The default path has no config file and uses the generic profile defaults; the configured path is an application adapter, not a Base repository convention.

Try the default policy and then the checked-in commerce policy:

$ northstar --quiet config show --format json
$ northstar --quiet --config examples/northstar-commerce.json status --format json
$ northstar --quiet --config examples/northstar-commerce.json release plan --format json

The config show command reports each normalized value and whether it came from the consumer default or the explicit file. Invalid JSON or unsupported values produce a safe configuration error with exit status 2. See docs/configuration.md for the schema and the profile boundary.

Development

Install the development extra and run the focused suite:

python -m pip install ".[dev]"
python -m pytest
./tests/validate.sh

The package requires Python 3.10 or newer and pins the supported Base-CLI line to >=0.4.3,<0.5. This checkout targets demo release v0.1.0; demo release versioning remains separate from framework versioning.

Repository shape

• src/base_cli_demo/cli.py contains the consumer-owned Click tree and the Base-CLI attachment boundary.
• src/base_cli_demo/fixtures/services.json contains deterministic local data.
• tests/test_cli.py exercises the installed lifecycle through the public testing helper.
• pyproject.toml defines the installable northstar console script.
• The generated Base repository files provide the project workflow and release contract; the demo itself does not require Base at runtime.

Base

This repository is managed by Base.

Common commands:

basectl setup base-cli-demo
basectl check base-cli-demo
basectl doctor base-cli-demo
basectl test base-cli-demo