From 474a56cd8aa18143e28f608513bce922a880e3b2 Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com> Date: Fri, 18 Sep 2026 22:16:42 +0530 Subject: [PATCH 1/2] docs(guide): explain the value Base-CLI adds to Northstar --- README.md | 16 ++++++++++++++++ docs/why-base-cli.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+) create mode 100644 docs/why-base-cli.md diff --git a/README.md b/README.md index f6993ca..cb00624 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,22 @@ 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`](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](docs/why-base-cli.md). + ## Quick start From a fresh checkout: diff --git a/docs/why-base-cli.md b/docs/why-base-cli.md new file mode 100644 index 0000000..43ac18c --- /dev/null +++ b/docs/why-base-cli.md @@ -0,0 +1,29 @@ +# Why base-cli? + +Every CLI application chooses how to define commands. A production CLI also +needs a repeatable contract around each command: where logs go, how errors map +to exit status, where temporary and run data live, how cleanup runs, and how +automation requests structured output. Without a shared lifecycle layer, each +application decides, implements, and tests those details for itself. + +Base-CLI composes with Click (and can attach to Typer); it is not a replacement +parser. It supplies the invocation lifecycle and public output/runtime APIs, +while the consumer keeps its command tree, configuration policy, and domain +behavior. + +| Shared concern | Northstar example | What the framework supplies | +| --- | --- | --- | +| Human and machine output | `northstar status --format json` | Public record renderers and stable JSON records. | +| Automation envelope | `northstar --json status --format json` | A versioned success/error envelope and the command's exit status. | +| Safe state-changing workflow | `northstar --dry-run release reconcile` | A lifecycle dry-run flag and consistent invocation context; Northstar decides what its local demo operation means. | +| Diagnostics | `--debug --log-file ... release reconcile` | Lifecycle logging, log placement, and registered sensitive-argument redaction. | +| Per-run files and cleanup | `release reconcile` | Managed runtime/temp paths and cleanup hooks; Northstar owns its state record. | + +## What this demo still owns + +The framework does not decide Northstar's service schema, which services belong +to an environment, the default target version, or the meaning of +`release reconcile`. Those choices remain in the consumer's Click commands, +fixtures, and configuration adapter. The boundary is visible in +[`src/base_cli_demo/cli.py`](../src/base_cli_demo/cli.py) and +[`src/base_cli_demo/profile.py`](../src/base_cli_demo/profile.py). From f5d3ed80b03faf7d16197ecc3b3593131018866c Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com> Date: Sat, 19 Sep 2026 16:26:02 +0530 Subject: [PATCH 2/2] docs: clarify the concrete Base-CLI value proposition --- docs/why-base-cli.md | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/why-base-cli.md b/docs/why-base-cli.md index 43ac18c..4851a35 100644 --- a/docs/why-base-cli.md +++ b/docs/why-base-cli.md @@ -16,14 +16,28 @@ behavior. | Human and machine output | `northstar status --format json` | Public record renderers and stable JSON records. | | Automation envelope | `northstar --json status --format json` | A versioned success/error envelope and the command's exit status. | | Safe state-changing workflow | `northstar --dry-run release reconcile` | A lifecycle dry-run flag and consistent invocation context; Northstar decides what its local demo operation means. | -| Diagnostics | `--debug --log-file ... release reconcile` | Lifecycle logging, log placement, and registered sensitive-argument redaction. | +| Diagnostics | `northstar --debug --log-file ... release reconcile` | Lifecycle logging, log placement, and registered sensitive-argument redaction. | | Per-run files and cleanup | `release reconcile` | Managed runtime/temp paths and cleanup hooks; Northstar owns its state record. | -## What this demo still owns +## What would otherwise be hand-written -The framework does not decide Northstar's service schema, which services belong -to an environment, the default target version, or the meaning of -`release reconcile`. Those choices remain in the consumer's Click commands, -fixtures, and configuration adapter. The boundary is visible in -[`src/base_cli_demo/cli.py`](../src/base_cli_demo/cli.py) and -[`src/base_cli_demo/profile.py`](../src/base_cli_demo/profile.py). +The small consumer entry point in [`src/base_cli_demo/cli.py`](../src/base_cli_demo/cli.py) +still owns the Click command tree and domain behavior. Without Base-CLI, that +same file would also need to hand-write and test the surrounding lifecycle: + +- turn `--environment`, `--dry-run`, `--json`, `--debug`, `--log-file`, and + `--keep-temp` into a consistent invocation context; +- choose state and temporary directories, run cleanup callbacks, and preserve + the dry-run boundary around `release reconcile`; +- route records through text/JSON/CSV/TSV/NDJSON output and emit the structured + success/error envelope used by automation; and +- configure logging, redact `approval_token`, and map command failures to stable + exit status. + +Those are the production-shaped behaviors supplied by Base-CLI and exercised +through its public facade. Northstar still decides its service fixture schema, +environment selection, target-version policy, and the meaning of +`release reconcile`; those decisions remain in the Click commands and +[`src/base_cli_demo/profile.py`](../src/base_cli_demo/profile.py). The README's +[framework boundary](../README.md#framework-boundary) is the concise ownership +summary.