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.

Why base-cli?

Click gives Northstar its command tree; Base-CLI adds the shared work around each invocation so the application does not have to build and maintain its own logging lifecycle, runtime paths, cleanup hooks, and machine-output contract. That is useful when a CLI is used by both people and automation, especially when commands need predictable JSON, actionable errors, safe diagnostics, or dry-run behavior. For a one-off command without those needs, plain Click may be the simpler choice.

In this demo, src/base_cli_demo/cli.py owns the Northstar commands and service policy. Its base_cli.App, app.attach(...), and base_cli.run_app(...) wiring delegates the invocation lifecycle to the framework; status and release reconcile show that boundary in use. See the full value and responsibility map.

Quick start

From a fresh checkout:

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

Install an existing release

To install the first published demo release without cloning the repository:

python -m pip install \
  "https://github.com/basefoundry/base-cli-demo/releases/download/v0.1.0/base_cli_demo-0.1.0-py3-none-any.whl"

Verify the artifact against SHA256SUMS.txt on the same GitHub Release. The wheel depends on the released base-cli>=0.4.3,<0.5 API line; it does not install Base or require a Base workspace.

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.

Deciding whether this framework fits your project? Read the adoption decision guide for its current stability, trade-offs, and alternatives.

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 YAML output guide explains its optional renderer extra and the preflight behavior when it is absent.
• 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 authoritative consumer gate (which checks the installed environment and runs the complete suite, including the documented-command smoke tests):

python -m pip install ".[dev]"
./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.

Documentation

Follow the documentation index for an ordered path from adoption decision through the Northstar walkthrough, compatibility, and release. To start with a minimal consumer rather than the full demo, use the copyable starter.

For framework-level material, start at the Base-CLI repository, its getting-started guide, or the public API reference.

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