From 36d58e8988730ac0f4723afb335afba31e9c4641 Mon Sep 17 00:00:00 2001
From: Joseph Doherty <dohejw01@gmail.com>
Date: Wed, 20 May 2026 22:03:32 -0400
Subject: [PATCH] docs(cli): document scadalink audit group + audit-config
 rename (#23 M8)

---
 src/ScadaLink.CLI/README.md | 113 ++++++++++++++++++++++++++++++++++--
 1 file changed, 109 insertions(+), 4 deletions(-)

diff --git a/src/ScadaLink.CLI/README.md b/src/ScadaLink.CLI/README.md
index 134af60..8c76d4c 100644
--- a/src/ScadaLink.CLI/README.md
+++ b/src/ScadaLink.CLI/README.md
@@ -1049,14 +1049,119 @@ Features:
 
 ---
 
-### `audit-log` — Audit log queries
+### `audit` — Centralized Audit Log
 
-#### `audit-log query`
+Read access to the central append-only **Audit Log** (#23) — the record of every
+script-trust-boundary action: outbound API calls (sync + cached), outbound DB
+operations (sync + cached), notifications, and inbound API calls. This is distinct
+from the configuration-change audit trail exposed by [`audit-config`](#audit-config--configuration-change-audit-log).
 
-Query the central audit log with optional filters and pagination.
+The subcommands map directly onto the `GET /api/audit/query` and
+`GET /api/audit/export` management endpoints. Filters and the result columns mirror
+the Central UI **Audit** page, so a CLI query and a UI query with the same filters
+return the same rows — CLI ↔ UI filter parity is intentional.
+
+**Permissions.** Querying requires the `OperationalAudit` permission (roles `Admin`,
+`Audit`, or `AuditReadOnly`). Exporting requires the stricter `AuditExport` permission
+(roles `Admin` or `Audit`) — read access does *not* imply export access. A request
+without the required role returns exit code `2`.
+
+#### `audit query`
+
+Query audit log events with optional filters and keyset pagination.
 
 ```sh
-scadalink --url <url> audit-log query [options]
+scadalink --url <url> audit query [options]
+```
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `--since` | no | — | Start time: relative (`1h`, `24h`, `7d`) or ISO-8601 |
+| `--until` | no | — | End time: relative (`1h`, `24h`, `7d`) or ISO-8601 |
+| `--channel` | no | — | Filter by channel (`OutboundApi`, `OutboundDb`, `Notification`, `InboundApi`) |
+| `--kind` | no | — | Filter by event kind |
+| `--status` | no | — | Filter by status (single value) |
+| `--site` | no | — | Filter by source site ID |
+| `--instance` | no | — | Filter by instance |
+| `--target` | no | — | Filter by target (external system, DB connection, notification list) |
+| `--actor` | no | — | Filter by actor |
+| `--correlation-id` | no | — | Filter by correlation ID |
+| `--errors-only` | no | `false` | Show only failed events (`status=Failed`; overrides `--status`) |
+| `--page-size` | no | `100` | Events per page (1–1000) |
+| `--all` | no | `false` | Fetch every page, following the keyset cursor |
+| `--format` | no | `json` | Output format: `json` (JSONL, one event per line) or `table` |
+
+With `--format table`, events render as an aligned text table with columns
+`OccurredAtUtc`, `Channel`, `Kind`, `Status`, `Target`, `Actor`, `DurationMs`,
+`HttpStatus`; long `Target`/`Actor` values are truncated with an ellipsis. With
+`--format json` (the default), each page is emitted as JSONL — one JSON object per
+line — which streams cleanly under `--all` across many pages.
+
+#### `audit export`
+
+Export audit log events to a file. The export streams from the server, so it is not
+bounded by the query page size.
+
+```sh
+scadalink --url <url> audit export --since <time> --until <time> --format <fmt> --output <path> [filters]
+```
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `--since` | yes | — | Start time: relative (`1h`, `24h`, `7d`) or ISO-8601 |
+| `--until` | yes | — | End time: relative (`1h`, `24h`, `7d`) or ISO-8601 |
+| `--format` | yes | — | Export format: `csv`, `jsonl`, or `parquet` |
+| `--output` | yes | — | Destination file path |
+| `--channel` | no | — | Filter by channel |
+| `--kind` | no | — | Filter by event kind |
+| `--status` | no | — | Filter by status |
+| `--site` | no | — | Filter by source site ID |
+| `--target` | no | — | Filter by target |
+| `--actor` | no | — | Filter by actor |
+
+> `--format parquet` is accepted by the CLI but the server returns `501 Not
+> Implemented` — Parquet archival is deferred to v1.x (see `Component-AuditLog.md`).
+> Use `csv` or `jsonl`.
+
+#### `audit verify-chain`
+
+Verify the audit log hash chain for a given month.
+
+```sh
+scadalink --url <url> audit verify-chain --month <YYYY-MM>
+```
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `--month` | yes | — | Month to verify, `YYYY-MM` (e.g. `2026-05`) |
+
+> **v1 no-op.** Hash-chain tamper-evidence is not enabled in this release. The
+> subcommand validates the `--month` argument and prints a notice pointing at the
+> v1.x roadmap in `Component-AuditLog.md`; it exits `0` without contacting the server.
+> The command exists now so scripts and operator habits do not need to change when
+> tamper-evidence ships.
+
+---
+
+### `audit-config` — Configuration-change audit log
+
+Query the configuration-change audit trail (the `IAuditService` record of admin
+edits to templates, instances, sites, etc.). This is **separate** from the
+centralized [`audit`](#audit--centralized-audit-log) group above.
+
+> **Renamed.** This group was named `audit-log` before #23 M8. The old name still
+> works as a deprecated alias — `scadalink audit-log query ...` resolves the full
+> subcommand tree unchanged — but prints a deprecation warning to stderr:
+> `Warning: 'audit-log' is deprecated and will be removed in a future release. Use 'audit-config' instead.`
+> Migrate scripts to `audit-config`; the `audit-log` alias will be removed in a
+> future release.
+
+#### `audit-config query`
+
+Query the configuration-change audit log with optional filters and pagination.
+
+```sh
+scadalink --url <url> audit-config query [options]
 ```
 
 | Option | Required | Default | Description |