UP

docs/09_API_CLI_REFERENCE.md

@@ -183,21 +183,79 @@ Validation errors come back as:
 
 ---
 
-### 2.4 Attestation (Planned – Q1‑2026)
-
-```
-POST /attest
-```
+### 2.4 Attestation (Planned – Q1‑2026)
+
+```
+POST /attest
+```
 
 | Param       | Purpose                               |
 | ----------- | ------------------------------------- |
 | body (JSON) | SLSA v1.0 provenance doc              |
 |             | Signed + stored in local Rekor mirror |
-
-Returns `202 Accepted` and `Location: /attest/{id}` for async verify.
-
----
-
+
+Returns `202 Accepted` and `Location: /attest/{id}` for async verify.
+
+---
+
+## 3 StellaOps CLI (`stellaops-cli`)
+
+The new CLI is built on **System.CommandLine 2.0.0‑beta5** and mirrors the Feedser backend REST API.  
+Configuration follows the same precedence chain everywhere:
+
+1. Environment variables (e.g. `API_KEY`, `STELLAOPS_BACKEND_URL`, `StellaOps:ApiKey`)  
+2. `appsettings.json` → `appsettings.local.json`  
+3. `appsettings.yaml` → `appsettings.local.yaml`  
+4. Defaults (`ApiKey = ""`, `BackendUrl = ""`, cache folders under the current working directory)
+
+| Command | Purpose | Key Flags / Arguments | Notes |
+|---------|---------|-----------------------|-------|
+| `stellaops-cli scanner download` | Fetch and install scanner container | `--channel <stable\|beta\|nightly>` (default `stable`)<br>`--output <path>`<br>`--overwrite`<br>`--no-install` | Saves artefact under `ScannerCacheDirectory`, verifies digest/signature, and executes `docker load` unless `--no-install` is supplied. |
+| `stellaops-cli scan run` | Execute scanner container against a directory (auto-upload) | `--target <directory>` (required)<br>`--runner <docker\|dotnet\|self>` (default from config)<br>`--entry <image-or-entrypoint>`<br>`[scanner-args...]` | Runs the scanner, writes results into `ResultsDirectory`, and automatically uploads the artefact when the exit code is `0`. |
+| `stellaops-cli scan upload` | Re-upload existing scan artefact | `--file <path>` | Useful for retries when automatic upload fails or when operating offline. |
+| `stellaops-cli db fetch` | Trigger connector jobs | `--source <id>` (e.g. `redhat`, `osv`)<br>`--stage <fetch\|parse\|map>` (default `fetch`)<br>`--mode <resume|init|cursor>` | Translates to `POST /jobs/source:{source}:{stage}` with `trigger=cli` |
+| `stellaops-cli db merge` | Run canonical merge reconcile | — | Calls `POST /jobs/merge:reconcile`; exit code `0` on acceptance, `1` on failures/conflicts |
+| `stellaops-cli db export` | Kick JSON / Trivy exports | `--format <json\|trivy-db>` (default `json`)<br>`--delta` | Sets `{ delta = true }` parameter when requested |
+| `stellaops-cli config show` | Display resolved configuration | — | Masks secret values; helpful for air‑gapped installs |
+
+**Logging & exit codes**
+
+- Structured logging via `Microsoft.Extensions.Logging` with single-line console output (timestamps in UTC).  
+- `--verbose / -v` raises log level to `Debug`.  
+- Command exit codes bubble up: backend conflict → `1`, cancelled via `CTRL+C` → `130`, scanner exit codes propagate as-is.
+
+**Artifact validation**
+
+- Downloads are verified against the `X-StellaOps-Digest` header (SHA-256). When `StellaOps:ScannerSignaturePublicKeyPath` points to a PEM-encoded RSA key, the optional `X-StellaOps-Signature` header is validated as well.
+- Metadata for each bundle is written alongside the artefact (`*.metadata.json`) with digest, signature, source URL, and timestamps.
+- Retry behaviour is controlled via `StellaOps:ScannerDownloadAttempts` (default **3** with exponential backoff).
+- Successful `scan run` executions create timestamped JSON artefacts inside `ResultsDirectory`; these are posted back to Feedser automatically.
+
+**Authentication**
+
+- API key is sent as `Authorization: Bearer <token>` automatically when configured.  
+- Anonymous operation (empty key) is permitted for offline use cases but backend calls will fail with 401 unless the Feedser instance allows guest access.
+
+**Configuration file template**
+
+```jsonc
+{
+  "StellaOps": {
+    "ApiKey": "your-api-token",
+    "BackendUrl": "https://feedser.example.org",
+    "ScannerCacheDirectory": "scanners",
+    "ResultsDirectory": "results",
+    "DefaultRunner": "docker",
+    "ScannerSignaturePublicKeyPath": "",
+    "ScannerDownloadAttempts": 3
+  }
+}
+```
+
+Drop `appsettings.local.json` or `.yaml` beside the binary to override per environment.
+
+---
+
 ### 2.5 Misc Endpoints
 
 | Path       | Method | Description                  |