docs(operate): auto-generate operator cli-reference.md (#23382)

## Summary

Adds an auto-generator for
`docs/docs-operate/operators/reference/cli-reference.md`. The file was
previously hand-maintained and silently drifted between v4.2.x and
v4.3.0 (`--pxe` flag removed, `--local-network.testAccounts` added, ~450
lines of help-text drift across other flags).

The developer-facing CLI references (`aztec`, `aztec-wallet`,
`aztec-up`) already auto-generate via `scan_cli.py` +
`cli_docs_config.json`, but `aztec start` is a single flag-list dump
rather than a recursive command tree, so a simpler dedicated script
makes more sense than retrofitting the existing framework.

## What changed

- **New script:**
`scripts/cli_reference_generation/generate_operator_cli_ref.sh` runs
`aztec start --help` and concatenates with the hand-curated preamble.
Retries on truncated output (the dockerized CLI sometimes drops trailing
stdout when captured via `$(...)` subshell — fixed by writing to a temp
file).
- **New preamble file:**
`scripts/cli_reference_generation/operator_cli_preamble.md` holds the
hand-curated frontmatter + intro.
- **New yarn script:** `generate:operator-cli-reference` in
`docs/package.json`.
- **Batch integration:** `generate_all_cli_docs.sh` now also generates
the operator ref (skipped when `OUTPUT_DIR` is set, since that's the
per-version flow which doesn't touch the operator doc).
- **README updated** with a note explaining the side-path.
- **Regenerated** `docs-operate/operators/reference/cli-reference.md`
via the new pipeline (982 lines). The diff vs `next` reflects what
should have been a v4.3.0 hand-update but never happened.

## Why this isn't part of `cli_docs_config.json`

The existing `scan_cli.py` infrastructure walks subcommand trees and
parses `Commands:` / `Subcommands:` sections. `aztec start` has no
subcommands — it's one command with ~950 flag descriptions. Folding it
into the existing config would require either special-casing inside
`scan_cli.py` or duplicating the preamble handling. A 70-line standalone
script is simpler.

## Out of scope

`scan_cli.py` exhibits the same dockerized-CLI stdout-truncation bug
(visible in the dev `aztec_cli_reference.md` line 1937 where "Default"
is truncated to "Defau"). Worth fixing in a follow-up — same root cause,
different code path.

## Test plan

- [x] `yarn generate:operator-cli-reference` produces 982-line output
ending cleanly with the TXE section
- [x] `./scripts/cli_reference_generation/generate_all_cli_docs.sh
--force current` triggers the new step at the end of the batch
- [x] Retry logic activates and recovers on flaky CLI runs
- [ ] CI build runs cleanly

Author: critesjosh

.claude/skills/release-network-docs/SKILL.md

@@ -192,6 +192,28 @@ if needed).
 Verify the output lists the expected number of methods and has no ungrouped
 methods warnings.
 
+### Step 5b: Regenerate Operator CLI Reference
+
+The operator-facing CLI reference (`docs/docs-operate/operators/reference/cli-reference.md`)
+is auto-generated from `aztec start --help`. Regenerate it so the doc matches
+the CLI shipped with the release.
+
+Pass the release version with `-v` so the script verifies the locally-installed
+`aztec` CLI matches before running. The mismatch is fatal in non-interactive
+mode (use `-f` to bypass).
+
+```bash
+cd docs
+yarn generate:operator-cli-reference -v v<new_version>
+```
+
+If `aztec --version` reports a different version, install the matching one
+first with `aztec-up v<new_version>` and retry.
+
+The script captures `aztec start --help`, retries on the dockerized-CLI
+stdout-truncation race, and writes the file. Verify the resulting file is
+~950+ lines and ends with `Starts Aztec TXE with options`.
+
 ### Step 6: Build and Validate
 
 Set the environment variables matching the release type so the build
@@ -306,13 +328,18 @@ Check for stash conflicts. Then report to the user:
 - **Some addresses are not in the RPC**: Contracts like Staking Registry,
   Reward Booster, Tally Slashing Proposer, and others must be queried on-chain,
   obtained from deployment output, or confirmed unchanged by the user.
-- **No heavy prerequisites**: This skill does not require aztec CLI, nargo, or
-  a yarn-project build. Only `yarn` (for the docs build), `curl`/`jq` (for
-  the RPC query), and `cast` (for on-chain address queries) are needed.
+- **Lightweight prerequisites**: This skill does not require nargo or a
+  yarn-project build. It does need: the locally-installed `aztec` CLI to match
+  the release version (for Step 5b), `yarn` (for the docs build), `curl`/`jq`
+  (for the RPC query), and `cast` (for on-chain address queries).
 - **Node API reference is auto-generated**: Run `yarn generate:node-api-reference`
   (Step 5a) before building. The generator parses TypeScript source directly, so
   no yarn-project build is required — but `yarn-project/node_modules/` must exist
   (run `yarn install` from `yarn-project` if missing).
+- **Operator CLI reference is auto-generated**: Run `yarn generate:operator-cli-reference`
+  (Step 5b) before building. The script runs `aztec start --help` and prepends
+  the hand-curated frontmatter/intro. Requires the matching `aztec` CLI version
+  to be installed locally.
 - **Build must pass**: Do not cut versioned docs until `yarn build` succeeds.
 - **COMMIT_TAG needs `v` prefix**: The preprocessor uses COMMIT_TAG for GitHub
   URLs and git tag references. Omitting the `v` will break links in versioned

docs/package.json

@@ -12,6 +12,7 @@
     "generate:aztec-nr-api": "./scripts/aztec_nr_docs_generation/generate_aztec_nr_docs.sh",
     "generate:typescript-api": "./scripts/typescript_api_generation/generate_ts_api_docs.sh",
     "generate:node-api-reference": "./scripts/node_api_reference_generation/generate_node_api_reference.sh",
+    "generate:operator-cli-reference": "./scripts/cli_reference_generation/generate_operator_cli_ref.sh",
     "preprocess": "yarn node -r dotenv/config ./src/preprocess/index.js",
     "preprocess:move": "sh scripts/move_processed.sh",
     "serve": "yarn docusaurus serve",

docs/scripts/cli_reference_generation/CLI_DOCS_README.md

@@ -15,6 +15,16 @@ The system supports multiple CLIs:
 - **Aztec Wallet CLI** (`aztec-wallet`) - Wallet-specific commands
 - **Aztec Version Manager** (`aztec-up`) - Version management tool
 
+Additionally, the operator-facing `aztec start` reference is generated by a
+separate, simpler script (`generate_operator_cli_ref.sh`) and is wired into
+the same batch run. It bypasses `scan_cli.py` because `aztec start` is a
+single flag-list dump rather than a recursive command tree. The script
+concatenates a hand-curated preamble (`operator_cli_preamble.md`) with the
+fenced output of `aztec start --help` and writes
+`docs-operate/operators/reference/cli-reference.md`. Run it directly via
+`yarn generate:operator-cli-reference` or as part of
+`generate_all_cli_docs.sh`.
+
 ## Quick Start
 
 ### Step 1: Scan the CLI

docs/scripts/cli_reference_generation/generate_all_cli_docs.sh

@@ -90,6 +90,20 @@ for cli in "${VALID_CLIS[@]}"; do
   echo ""
 done
 
+# Also regenerate the operator-facing `aztec start` reference. It is not
+# in cli_docs_config.json because it's a single flag-list dump rather than a
+# recursive command tree, and bypasses scan_cli.py. Only regenerate it for
+# the default/current flow — when OUTPUT_DIR is set or a specific historical
+# version is being targeted, the operator ref (which always reflects the
+# currently-installed CLI) isn't part of that flow.
+if [[ -z "$OUTPUT_DIR" ]] && [[ "$TARGET_VERSION" == "all" || "$TARGET_VERSION" == "current" ]]; then
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "Generating Operator (aztec start) CLI Reference"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "$SCRIPT_DIR/generate_operator_cli_ref.sh"
+  echo ""
+fi
+
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo "✅ All CLI Documentation Generated"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
@@ -103,6 +117,9 @@ for cli in "${VALID_CLIS[@]}"; do
     echo "  - $CLI_OUTPUT_FILE"
   fi
 done
+if [[ -z "$OUTPUT_DIR" ]] && [[ "$TARGET_VERSION" == "all" || "$TARGET_VERSION" == "current" ]]; then
+  echo "  - operators/reference/cli-reference.md"
+fi
 echo ""
 if [[ -z "$OUTPUT_DIR" ]]; then
   echo "You can now commit these changes to the repository."

docs/scripts/cli_reference_generation/generate_operator_cli_ref.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# Regenerate docs/docs-operate/operators/reference/cli-reference.md from the
+# `aztec start --help` output of the locally-installed aztec CLI.
+#
+# Unlike the developer-facing CLI references (aztec, aztec-wallet, aztec-up),
+# this file is a flag-list dump rather than a recursive command tree, so it
+# bypasses scan_cli.py. The hand-curated frontmatter + intro live in a
+# preamble file; this script concatenates the preamble with a fenced
+# `aztec start --help` capture.
+#
+# NOTE: `aztec start --help` runs through the dockerized aztec wrapper, which
+# occasionally drops trailing stdout (the container exits before the parent
+# drains the pipe) or exits non-zero. The retry loop below is the real
+# safeguard: it re-runs until the captured output contains the final help line.
+#
+# Usage:
+#   ./generate_operator_cli_ref.sh                          # default target, no version check
+#   ./generate_operator_cli_ref.sh /tmp/out.md              # custom target
+#   ./generate_operator_cli_ref.sh -v v4.3.0                # warn if installed CLI != v4.3.0
+#   ./generate_operator_cli_ref.sh -v v4.3.0 -f             # force past version mismatch
+#
+# Options:
+#   -v, --version <ver>   Warn if installed `aztec --version` does not match
+#                         this target. In non-interactive mode the mismatch is
+#                         fatal unless --force is passed.
+#   -f, --force           Skip the version-mismatch confirmation prompt.
+#
+# Run from any cwd — paths are resolved relative to the script location.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DOCS_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PREAMBLE="$SCRIPT_DIR/operator_cli_preamble.md"
+DEFAULT_TARGET="$DOCS_ROOT/docs-operate/operators/reference/cli-reference.md"
+MAX_ATTEMPTS=3
+
+TARGET=""
+TARGET_VERSION=""
+FORCE_MODE=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -v|--version)
+      if [[ $# -lt 2 ]]; then
+        echo "ERROR: $1 requires a value (e.g. -v v4.3.0)" >&2
+        exit 1
+      fi
+      TARGET_VERSION="$2"
+      shift 2
+      ;;
+    -f|--force)
+      FORCE_MODE=true
+      shift
+      ;;
+    -h|--help)
+      sed -n '2,28p' "$0" | sed 's/^# \{0,1\}//'
+      exit 0
+      ;;
+    -*)
+      echo "ERROR: unknown option: $1" >&2
+      exit 1
+      ;;
+    *)
+      if [[ -z "$TARGET" ]]; then
+        TARGET="$1"
+        shift
+      else
+        echo "ERROR: unexpected extra positional argument: $1" >&2
+        exit 1
+      fi
+      ;;
+  esac
+done
+TARGET="${TARGET:-$DEFAULT_TARGET}"
+
+if [[ ! -f "$PREAMBLE" ]]; then
+  echo "ERROR: preamble file not found at $PREAMBLE" >&2
+  exit 1
+fi
+
+if ! command -v aztec >/dev/null 2>&1; then
+  echo "ERROR: 'aztec' CLI not found on PATH. Install with aztec-up first." >&2
+  exit 1
+fi
+
+# Optional version check — mirrors the pattern used by generate_cli_docs.sh.
+# Advisory: warns and either prompts or fails non-interactively. Bypassable
+# with --force, since CI flows build a wrapper around a freshly-built CLI
+# whose `--version` may not equal the target tag.
+if [[ -n "$TARGET_VERSION" ]]; then
+  INSTALLED_VER="$(aztec --version 2>/dev/null | head -n1 \
+    | grep -oE '[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?' | head -n1 || true)"
+  TARGET_NORMALIZED="${TARGET_VERSION#v}"
+
+  if [[ "$INSTALLED_VER" != "$TARGET_NORMALIZED" ]]; then
+    echo "" >&2
+    echo "WARNING: aztec CLI version mismatch" >&2
+    echo "  Installed: ${INSTALLED_VER:-unknown}" >&2
+    echo "  Target:    $TARGET_NORMALIZED" >&2
+    echo "  To fix:    aztec-up v$TARGET_NORMALIZED" >&2
+    echo "" >&2
+
+    if [[ "$FORCE_MODE" == true ]]; then
+      echo "Force mode enabled, continuing with mismatched version..." >&2
+    elif [[ -t 0 ]]; then
+      read -p "Continue anyway? (y/N): " -n 1 -r
+      echo ""
+      if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        echo "Aborted. Install the matching CLI version and retry." >&2
+        exit 1
+      fi
+    else
+      echo "ERROR: version mismatch in non-interactive mode. Use --force to bypass." >&2
+      exit 1
+    fi
+  else
+    echo "CLI version check passed: aztec v$INSTALLED_VER"
+  fi
+fi
+
+HELP_FILE="$(mktemp)"
+ERR_FILE="$(mktemp)"
+TMP="$(mktemp)"
+trap 'rm -f "$HELP_FILE" "$ERR_FILE" "$TMP"' EXIT INT TERM
+
+# Capture into a file (not a shell variable) and validate completeness by the
+# presence of the final help line ("Starts Aztec TXE with options"), not just
+# the "TXE" section header — a dropped tail can omit the trailing flag and its
+# description while still emitting the header. This sentinel tracks the last
+# entry in yarn-project/aztec/src/cli/aztec_start_options.ts; update it if that
+# block is reworded or reordered.
+#
+# `|| true` keeps a non-zero exit (which the same flush race can produce) from
+# aborting the loop under `set -e`, so the retry actually covers that failure
+# mode; the sentinel check below is the real success signal. stderr is captured
+# rather than discarded so a genuine failure (missing image, daemon down) is
+# surfaced instead of masquerading as truncation.
+for attempt in $(seq 1 "$MAX_ATTEMPTS"); do
+  COLUMNS=200 aztec start --help >"$HELP_FILE" 2>"$ERR_FILE" || true
+
+  if grep -qF 'Starts Aztec TXE with options' "$HELP_FILE"; then
+    break
+  fi
+
+  LINES="$(wc -l < "$HELP_FILE")"
+  if [[ "$attempt" -lt "$MAX_ATTEMPTS" ]]; then
+    echo "WARN: 'aztec start --help' output incomplete, trailing TXE description missing (attempt $attempt/$MAX_ATTEMPTS, $LINES lines), retrying..." >&2
+    sleep 1
+  else
+    echo "ERROR: 'aztec start --help' kept producing incomplete output after $MAX_ATTEMPTS attempts ($LINES lines)." >&2
+    echo "       Last line: '$(tail -1 "$HELP_FILE" | cut -c1-80)...'" >&2
+    if [[ -s "$ERR_FILE" ]]; then
+      echo "       stderr from the final attempt:" >&2
+      sed 's/^/         /' "$ERR_FILE" >&2
+    fi
+    exit 1
+  fi
+done
+
+cat "$PREAMBLE" > "$TMP"
+echo '```bash' >> "$TMP"
+cat "$HELP_FILE" >> "$TMP"
+echo '```' >> "$TMP"
+
+# mktemp creates the temp file 0600; normalize before moving so the generated
+# doc doesn't land owner-only (mv preserves the source mode).
+chmod 644 "$TMP"
+mv "$TMP" "$TARGET"
+
+echo "Wrote $TARGET ($(wc -l < "$TARGET") lines)"

docs/scripts/cli_reference_generation/operator_cli_preamble.md

@@ -0,0 +1,30 @@
+---
+displayed_sidebar: operatorsSidebar
+title: Cli Reference
+description: A reference of the --help output when running aztec start.
+references: ["yarn-project/aztec/src/cli/aztec_start_options.ts", "yarn-project/aztec/src/cli/cli.ts"]
+keywords:
+  [
+    aztec,
+    prover,
+    node,
+    blockchain,
+    L2,
+    scaling,
+    ethereum,
+    zero-knowledge,
+    ZK,
+    setup,
+  ]
+tags:
+  - prover
+  - node
+  - tutorial
+  - infrastructure
+---
+
+**Configuration notes:**
+
+- The environment variable name corresponding to each flag is shown as $ENV_VAR on the right hand side.
+- If two subsystems can contain the same configuration option, only one needs to be provided. For example, `--archiver.blobSinkUrl` and `--sequencer.blobSinkUrl` point to the same value.
+