From 9e3274313f5c341c5bccf8d0a9d78f9ad3f29c87 Mon Sep 17 00:00:00 2001 From: dkijania Date: Sun, 15 Mar 2026 20:44:37 +0100 Subject: [PATCH 1/8] Add CLI reference generation script Add a helper script to auto-generate CLI reference documentation from mina daemon --help output. Co-Authored-By: Claude Opus 4.6 (1M context) --- scripts/generate-cli-reference.sh | 111 ++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 scripts/generate-cli-reference.sh diff --git a/scripts/generate-cli-reference.sh b/scripts/generate-cli-reference.sh new file mode 100644 index 000000000..3ff6dd8d1 --- /dev/null +++ b/scripts/generate-cli-reference.sh @@ -0,0 +1,111 @@ +#!/usr/bin/env bash +# Script to generate Mina CLI reference documentation from the mina binary. +# +# This script captures the help output of each mina command group and formats +# it as markdown suitable for the docs website (docs.minaprotocol.com). +# +# Usage: +# ./scripts/generate-cli-reference.sh [path/to/mina] [output-dir] +# +# Arguments: +# path/to/mina Path to the mina executable (default: mina, assumes it's in PATH) +# output-dir Directory to write output files (default: /tmp/mina-cli-reference) +# +# Example: +# ./scripts/generate-cli-reference.sh \ +# _build/default/src/app/cli/src/mina.exe \ +# /tmp/mina-cli-reference + +set -euo pipefail + +MINA_BIN="${1:-mina}" +OUTPUT_DIR="${2:-/tmp/mina-cli-reference}" + +if ! (command -v "$MINA_BIN" &>/dev/null || [ -x "$MINA_BIN" ]); then + echo "Error: mina binary not found at '$MINA_BIN'" >&2 + echo "Build it first with: dune build src/app/cli/src/mina.exe" >&2 + exit 1 +fi + +mkdir -p "$OUTPUT_DIR" + +# Helper function to append help text for a command +append_help() { + local cmd="$1" + local output_file="$2" + local indent="${3:-}" + + # Capture the help text; use || true to handle non-zero exit from --help + local help_output + help_output="$("$MINA_BIN" $cmd --help 2>&1 || true)" + + printf '%s\n' "$help_output" >> "$output_file" + printf '\n' >> "$output_file" +} + +# Generate the top-level command reference +TOP_LEVEL_FILE="$OUTPUT_DIR/mina-cli-reference.md" +cat > "$TOP_LEVEL_FILE" <<'HEADER' +# Mina CLI Reference + +This document provides a reference for all Mina CLI commands. It is +auto-generated from the `mina` binary using `scripts/generate-cli-reference.sh`. + +HEADER + +echo "Generating CLI reference documentation..." + +# Top-level help +echo "## mina" >> "$TOP_LEVEL_FILE" +echo '```' >> "$TOP_LEVEL_FILE" +"$MINA_BIN" --help 2>&1 || true >> "$TOP_LEVEL_FILE" +echo '```' >> "$TOP_LEVEL_FILE" +echo "" >> "$TOP_LEVEL_FILE" + +# Define the main command groups to document +declare -a GROUPS=( + "accounts" + "client" + "advanced" + "ledger" + "libp2p" +) + +for group in "${GROUPS[@]}"; do + echo "## mina $group" >> "$TOP_LEVEL_FILE" + echo '```' >> "$TOP_LEVEL_FILE" + "$MINA_BIN" "$group" --help 2>&1 || true >> "$TOP_LEVEL_FILE" + echo '```' >> "$TOP_LEVEL_FILE" + echo "" >> "$TOP_LEVEL_FILE" + + # Get subcommands for this group + subcommand_output="$("$MINA_BIN" "$group" --help 2>&1 || true)" + + # Extract subcommand names from the help output + # Lines after "=== subcommands ===" are subcommands until next section or end + in_subcommands=false + while IFS= read -r line; do + if [[ "$line" == *"=== subcommands ==="* ]]; then + in_subcommands=true + continue + fi + if [[ "$in_subcommands" == true ]]; then + if [[ "$line" == *"==="* ]]; then + in_subcommands=false + continue + fi + # Extract the subcommand name (first word after leading whitespace) + subcmd="$(awk '{print $1}' <<< "$line")" + if [[ -n "$subcmd" ]]; then + echo "### mina $group $subcmd" >> "$TOP_LEVEL_FILE" + echo '```' >> "$TOP_LEVEL_FILE" + "$MINA_BIN" "$group" "$subcmd" --help 2>&1 || true >> "$TOP_LEVEL_FILE" + echo '```' >> "$TOP_LEVEL_FILE" + echo "" >> "$TOP_LEVEL_FILE" + fi + fi + done <<< "$subcommand_output" +done + +echo "CLI reference documentation generated in: $OUTPUT_DIR" +echo "Main file: $TOP_LEVEL_FILE" From 9222d788a19204244c0e4ecb548068409e979237 Mon Sep 17 00:00:00 2001 From: dkijania Date: Tue, 17 Mar 2026 00:26:24 +0100 Subject: [PATCH 2/8] add ci job --- .github/workflows/generate-cli-reference.yml | 45 ++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 .github/workflows/generate-cli-reference.yml diff --git a/.github/workflows/generate-cli-reference.yml b/.github/workflows/generate-cli-reference.yml new file mode 100644 index 000000000..ec492d942 --- /dev/null +++ b/.github/workflows/generate-cli-reference.yml @@ -0,0 +1,45 @@ +name: Generate CLI Reference + +on: + workflow_dispatch: {} + +jobs: + generate-cli-reference: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Install Mina daemon + run: | + echo "deb [trusted=yes] http://packages.o1test.net/ bookworm stable" | sudo tee /etc/apt/sources.list.d/mina.list + sudo apt-get update + sudo apt-get install -y mina-mainnet + + - name: Capture installed version + id: version + run: | + VERSION=$(dpkg-query -W -f='${Version}' mina-mainnet) + echo "mina_version=$VERSION" >> "$GITHUB_OUTPUT" + + - name: Generate CLI reference + run: | + chmod +x scripts/generate-cli-reference.sh + ./scripts/generate-cli-reference.sh mina /tmp/mina-cli-reference + + - name: Copy output to docs + run: | + cp /tmp/mina-cli-reference/mina-cli-reference.md docs/node-operators/mina-cli-reference.mdx + + - name: Create Pull Request + uses: peter-evans/create-pull-request@v6 + with: + commit-message: "Update CLI reference for mina ${{ steps.version.outputs.mina_version }}" + title: "Update CLI reference for mina ${{ steps.version.outputs.mina_version }}" + body: | + Auto-generated CLI reference from `mina` version `${{ steps.version.outputs.mina_version }}` (bookworm). + + Generated by `scripts/generate-cli-reference.sh`. + branch: auto/cli-reference-update + base: main From b6d11c99689ab38f94bf3b1a2cba5b2831bb4255 Mon Sep 17 00:00:00 2001 From: dkijania Date: Sun, 15 Mar 2026 20:44:37 +0100 Subject: [PATCH 3/8] Add CLI reference generation script Add a helper script to auto-generate CLI reference documentation from mina daemon --help output. Co-Authored-By: Claude Opus 4.6 (1M context) --- scripts/generate-cli-reference.sh | 111 ++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 scripts/generate-cli-reference.sh diff --git a/scripts/generate-cli-reference.sh b/scripts/generate-cli-reference.sh new file mode 100644 index 000000000..3ff6dd8d1 --- /dev/null +++ b/scripts/generate-cli-reference.sh @@ -0,0 +1,111 @@ +#!/usr/bin/env bash +# Script to generate Mina CLI reference documentation from the mina binary. +# +# This script captures the help output of each mina command group and formats +# it as markdown suitable for the docs website (docs.minaprotocol.com). +# +# Usage: +# ./scripts/generate-cli-reference.sh [path/to/mina] [output-dir] +# +# Arguments: +# path/to/mina Path to the mina executable (default: mina, assumes it's in PATH) +# output-dir Directory to write output files (default: /tmp/mina-cli-reference) +# +# Example: +# ./scripts/generate-cli-reference.sh \ +# _build/default/src/app/cli/src/mina.exe \ +# /tmp/mina-cli-reference + +set -euo pipefail + +MINA_BIN="${1:-mina}" +OUTPUT_DIR="${2:-/tmp/mina-cli-reference}" + +if ! (command -v "$MINA_BIN" &>/dev/null || [ -x "$MINA_BIN" ]); then + echo "Error: mina binary not found at '$MINA_BIN'" >&2 + echo "Build it first with: dune build src/app/cli/src/mina.exe" >&2 + exit 1 +fi + +mkdir -p "$OUTPUT_DIR" + +# Helper function to append help text for a command +append_help() { + local cmd="$1" + local output_file="$2" + local indent="${3:-}" + + # Capture the help text; use || true to handle non-zero exit from --help + local help_output + help_output="$("$MINA_BIN" $cmd --help 2>&1 || true)" + + printf '%s\n' "$help_output" >> "$output_file" + printf '\n' >> "$output_file" +} + +# Generate the top-level command reference +TOP_LEVEL_FILE="$OUTPUT_DIR/mina-cli-reference.md" +cat > "$TOP_LEVEL_FILE" <<'HEADER' +# Mina CLI Reference + +This document provides a reference for all Mina CLI commands. It is +auto-generated from the `mina` binary using `scripts/generate-cli-reference.sh`. + +HEADER + +echo "Generating CLI reference documentation..." + +# Top-level help +echo "## mina" >> "$TOP_LEVEL_FILE" +echo '```' >> "$TOP_LEVEL_FILE" +"$MINA_BIN" --help 2>&1 || true >> "$TOP_LEVEL_FILE" +echo '```' >> "$TOP_LEVEL_FILE" +echo "" >> "$TOP_LEVEL_FILE" + +# Define the main command groups to document +declare -a GROUPS=( + "accounts" + "client" + "advanced" + "ledger" + "libp2p" +) + +for group in "${GROUPS[@]}"; do + echo "## mina $group" >> "$TOP_LEVEL_FILE" + echo '```' >> "$TOP_LEVEL_FILE" + "$MINA_BIN" "$group" --help 2>&1 || true >> "$TOP_LEVEL_FILE" + echo '```' >> "$TOP_LEVEL_FILE" + echo "" >> "$TOP_LEVEL_FILE" + + # Get subcommands for this group + subcommand_output="$("$MINA_BIN" "$group" --help 2>&1 || true)" + + # Extract subcommand names from the help output + # Lines after "=== subcommands ===" are subcommands until next section or end + in_subcommands=false + while IFS= read -r line; do + if [[ "$line" == *"=== subcommands ==="* ]]; then + in_subcommands=true + continue + fi + if [[ "$in_subcommands" == true ]]; then + if [[ "$line" == *"==="* ]]; then + in_subcommands=false + continue + fi + # Extract the subcommand name (first word after leading whitespace) + subcmd="$(awk '{print $1}' <<< "$line")" + if [[ -n "$subcmd" ]]; then + echo "### mina $group $subcmd" >> "$TOP_LEVEL_FILE" + echo '```' >> "$TOP_LEVEL_FILE" + "$MINA_BIN" "$group" "$subcmd" --help 2>&1 || true >> "$TOP_LEVEL_FILE" + echo '```' >> "$TOP_LEVEL_FILE" + echo "" >> "$TOP_LEVEL_FILE" + fi + fi + done <<< "$subcommand_output" +done + +echo "CLI reference documentation generated in: $OUTPUT_DIR" +echo "Main file: $TOP_LEVEL_FILE" From 891182f0517a160f862997f77510ccfc7e34f82c Mon Sep 17 00:00:00 2001 From: dkijania Date: Tue, 17 Mar 2026 00:26:24 +0100 Subject: [PATCH 4/8] add ci job --- .github/workflows/generate-cli-reference.yml | 45 ++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 .github/workflows/generate-cli-reference.yml diff --git a/.github/workflows/generate-cli-reference.yml b/.github/workflows/generate-cli-reference.yml new file mode 100644 index 000000000..ec492d942 --- /dev/null +++ b/.github/workflows/generate-cli-reference.yml @@ -0,0 +1,45 @@ +name: Generate CLI Reference + +on: + workflow_dispatch: {} + +jobs: + generate-cli-reference: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Install Mina daemon + run: | + echo "deb [trusted=yes] http://packages.o1test.net/ bookworm stable" | sudo tee /etc/apt/sources.list.d/mina.list + sudo apt-get update + sudo apt-get install -y mina-mainnet + + - name: Capture installed version + id: version + run: | + VERSION=$(dpkg-query -W -f='${Version}' mina-mainnet) + echo "mina_version=$VERSION" >> "$GITHUB_OUTPUT" + + - name: Generate CLI reference + run: | + chmod +x scripts/generate-cli-reference.sh + ./scripts/generate-cli-reference.sh mina /tmp/mina-cli-reference + + - name: Copy output to docs + run: | + cp /tmp/mina-cli-reference/mina-cli-reference.md docs/node-operators/mina-cli-reference.mdx + + - name: Create Pull Request + uses: peter-evans/create-pull-request@v6 + with: + commit-message: "Update CLI reference for mina ${{ steps.version.outputs.mina_version }}" + title: "Update CLI reference for mina ${{ steps.version.outputs.mina_version }}" + body: | + Auto-generated CLI reference from `mina` version `${{ steps.version.outputs.mina_version }}` (bookworm). + + Generated by `scripts/generate-cli-reference.sh`. + branch: auto/cli-reference-update + base: main From 2c074cf6e6c3bbb9913fdc08d0cbe7c845dc8437 Mon Sep 17 00:00:00 2001 From: dkijania Date: Wed, 18 Mar 2026 00:13:18 +0100 Subject: [PATCH 5/8] ci: add PR and push triggers to CLI reference workflow - On PRs: check if CLI reference is outdated and fail with a diff if so - On push to main / workflow_dispatch: check + auto-create PR with update - Trigger on changes to the CLI reference doc, generation script, or workflow Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/workflows/generate-cli-reference.yml | 51 +++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/.github/workflows/generate-cli-reference.yml b/.github/workflows/generate-cli-reference.yml index ec492d942..2c036649b 100644 --- a/.github/workflows/generate-cli-reference.yml +++ b/.github/workflows/generate-cli-reference.yml @@ -2,9 +2,58 @@ name: Generate CLI Reference on: workflow_dispatch: {} + pull_request: + paths: + - 'docs/node-operators/mina-cli-reference.mdx' + - 'scripts/generate-cli-reference.sh' + - '.github/workflows/generate-cli-reference.yml' + push: + branches: + - main + paths: + - 'docs/node-operators/mina-cli-reference.mdx' + - 'scripts/generate-cli-reference.sh' + - '.github/workflows/generate-cli-reference.yml' jobs: - generate-cli-reference: + check-cli-reference: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Install Mina daemon + run: | + echo "deb [trusted=yes] http://packages.o1test.net/ bookworm stable" | sudo tee /etc/apt/sources.list.d/mina.list + sudo apt-get update + sudo apt-get install -y mina-mainnet + + - name: Capture installed version + id: version + run: | + VERSION=$(dpkg-query -W -f='${Version}' mina-mainnet) + echo "mina_version=$VERSION" >> "$GITHUB_OUTPUT" + + - name: Generate CLI reference + run: | + chmod +x scripts/generate-cli-reference.sh + ./scripts/generate-cli-reference.sh mina /tmp/mina-cli-reference + + - name: Check if CLI reference is outdated + run: | + cp /tmp/mina-cli-reference/mina-cli-reference.md /tmp/generated.mdx + if ! diff -q docs/node-operators/mina-cli-reference.mdx /tmp/generated.mdx > /dev/null 2>&1; then + echo "::warning::CLI reference is outdated (current mina version: ${{ steps.version.outputs.mina_version }})" + diff --unified docs/node-operators/mina-cli-reference.mdx /tmp/generated.mdx || true + exit 1 + else + echo "CLI reference is up to date with mina ${{ steps.version.outputs.mina_version }}" + fi + + update-cli-reference: + if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' + needs: check-cli-reference runs-on: ubuntu-latest steps: From bca57a621dd4a4de5c379af22ebd66192847ea94 Mon Sep 17 00:00:00 2001 From: dkijania Date: Wed, 8 Apr 2026 09:17:04 +0200 Subject: [PATCH 6/8] Fix CLI reference generation script redirect bugs and add frontmatter - Fix shell operator precedence in 3 places where `cmd 2>&1 || true >> file` was parsed as `(cmd) || (true >> file)`, causing empty code blocks - Add MDX frontmatter and intro text to match committed docs format - Add missing `daemon` group to GROUPS array Co-Authored-By: Claude Opus 4.6 (1M context) --- scripts/generate-cli-reference.sh | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/scripts/generate-cli-reference.sh b/scripts/generate-cli-reference.sh index 3ff6dd8d1..0a5084807 100644 --- a/scripts/generate-cli-reference.sh +++ b/scripts/generate-cli-reference.sh @@ -46,10 +46,28 @@ append_help() { # Generate the top-level command reference TOP_LEVEL_FILE="$OUTPUT_DIR/mina-cli-reference.md" cat > "$TOP_LEVEL_FILE" <<'HEADER' +--- +title: Mina CLI Reference +hide_title: true +description: Reference for the Mina CLI (command line interface) which is the primary way to interact with the Mina network. +keywords: + - Mina CLI + - create account + - send transaction + - reference +--- + # Mina CLI Reference -This document provides a reference for all Mina CLI commands. It is -auto-generated from the `mina` binary using `scripts/generate-cli-reference.sh`. +The Mina CLI (Command Line Interface) is the primary way for users to interact with the Mina network. It provides standard client functionality to create accounts, send transactions, and participate in consensus. There are also advanced client and daemon commands for power users. + +The Mina CLI is installed when you [install Mina](/node-operators/block-producer-node/getting-started#installation). + +:::tip + +Mina APIs are always improving. See `mina help` for the most up-to-date version. + +::: HEADER @@ -58,7 +76,7 @@ echo "Generating CLI reference documentation..." # Top-level help echo "## mina" >> "$TOP_LEVEL_FILE" echo '```' >> "$TOP_LEVEL_FILE" -"$MINA_BIN" --help 2>&1 || true >> "$TOP_LEVEL_FILE" +("$MINA_BIN" --help 2>&1 || true) >> "$TOP_LEVEL_FILE" echo '```' >> "$TOP_LEVEL_FILE" echo "" >> "$TOP_LEVEL_FILE" @@ -66,6 +84,7 @@ echo "" >> "$TOP_LEVEL_FILE" declare -a GROUPS=( "accounts" "client" + "daemon" "advanced" "ledger" "libp2p" @@ -74,7 +93,7 @@ declare -a GROUPS=( for group in "${GROUPS[@]}"; do echo "## mina $group" >> "$TOP_LEVEL_FILE" echo '```' >> "$TOP_LEVEL_FILE" - "$MINA_BIN" "$group" --help 2>&1 || true >> "$TOP_LEVEL_FILE" + ("$MINA_BIN" "$group" --help 2>&1 || true) >> "$TOP_LEVEL_FILE" echo '```' >> "$TOP_LEVEL_FILE" echo "" >> "$TOP_LEVEL_FILE" @@ -99,7 +118,7 @@ for group in "${GROUPS[@]}"; do if [[ -n "$subcmd" ]]; then echo "### mina $group $subcmd" >> "$TOP_LEVEL_FILE" echo '```' >> "$TOP_LEVEL_FILE" - "$MINA_BIN" "$group" "$subcmd" --help 2>&1 || true >> "$TOP_LEVEL_FILE" + ("$MINA_BIN" "$group" "$subcmd" --help 2>&1 || true) >> "$TOP_LEVEL_FILE" echo '```' >> "$TOP_LEVEL_FILE" echo "" >> "$TOP_LEVEL_FILE" fi From 055d1b47a35078411db414fc2215398028000efb Mon Sep 17 00:00:00 2001 From: dkijania Date: Wed, 8 Apr 2026 13:41:07 +0200 Subject: [PATCH 7/8] Rename GROUPS to CMD_GROUPS to avoid bash built-in collision GROUPS is a bash built-in array containing the current user's Unix group IDs, which silently overwrites the declared array values. Co-Authored-By: Claude Opus 4.6 (1M context) --- scripts/generate-cli-reference.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) mode change 100644 => 100755 scripts/generate-cli-reference.sh diff --git a/scripts/generate-cli-reference.sh b/scripts/generate-cli-reference.sh old mode 100644 new mode 100755 index 0a5084807..bb5df4b53 --- a/scripts/generate-cli-reference.sh +++ b/scripts/generate-cli-reference.sh @@ -81,7 +81,7 @@ echo '```' >> "$TOP_LEVEL_FILE" echo "" >> "$TOP_LEVEL_FILE" # Define the main command groups to document -declare -a GROUPS=( +declare -a CMD_GROUPS=( "accounts" "client" "daemon" @@ -90,7 +90,7 @@ declare -a GROUPS=( "libp2p" ) -for group in "${GROUPS[@]}"; do +for group in "${CMD_GROUPS[@]}"; do echo "## mina $group" >> "$TOP_LEVEL_FILE" echo '```' >> "$TOP_LEVEL_FILE" ("$MINA_BIN" "$group" --help 2>&1 || true) >> "$TOP_LEVEL_FILE" From 5ddec35b534294b241aa981baa4f2865562fc702 Mon Sep 17 00:00:00 2001 From: dkijania Date: Wed, 8 Apr 2026 14:00:27 +0200 Subject: [PATCH 8/8] Fix subcommand parser to skip continuation lines Multi-line subcommand descriptions have continuation lines with extra leading whitespace. Only parse lines matching the subcommand pattern (2 spaces + non-space) to avoid extracting description fragments. Co-Authored-By: Claude Opus 4.6 (1M context) --- scripts/generate-cli-reference.sh | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/scripts/generate-cli-reference.sh b/scripts/generate-cli-reference.sh index bb5df4b53..79e16d6c8 100755 --- a/scripts/generate-cli-reference.sh +++ b/scripts/generate-cli-reference.sh @@ -113,7 +113,11 @@ for group in "${CMD_GROUPS[@]}"; do in_subcommands=false continue fi - # Extract the subcommand name (first word after leading whitespace) + # Subcommand lines start with 2 spaces then a non-space char; + # continuation/description lines have more leading whitespace. + if [[ ! "$line" =~ ^\ \ [^\ ] ]]; then + continue + fi subcmd="$(awk '{print $1}' <<< "$line")" if [[ -n "$subcmd" ]]; then echo "### mina $group $subcmd" >> "$TOP_LEVEL_FILE"