Artificial Intelligence Linux Documentation Automation: Turn “--help” Into Living Docs

Ever merged a feature and thought “I’ll update the docs later,” then never did? Stale docs cost time, trust, and on-call sanity. The good news: you can automate 80% of Linux CLI documentation with AI—grounded in your actual --help, man pages, and git history—so docs stay accurate without heroics.

This post shows why AI-powered doc automation is worth doing and gives you 3–5 actionable Bash-centric steps, complete with install commands for apt, dnf, and zypper.

---

Why automate docs with AI?

• Drift is inevitable. CLI flags and behavior change faster than human-written docs. Automating from source-of-truth (help/man and code) keeps docs synchronized.

• Docs become a pipeline, not an afterthought. If you can run make docs or a Git hook, you can ship docs with every change.

• Privacy and cost control. With local models (Ollama), you can keep everything on-box, offline if needed.

• Better onboarding and fewer “how do I…” pings. Task-oriented, example-first Markdown beats raw --help dumps for most users.

---

Prerequisites and installation

We’ll use common CLI tools and optionally a local AI runtime (Ollama). Install these packages first.

• Debian/Ubuntu (apt):

sudo apt update
sudo apt install -y git curl jq help2man pandoc

• Fedora/RHEL/CentOS (dnf):

sudo dnf install -y git curl jq help2man pandoc

• openSUSE (zypper):

sudo zypper refresh
sudo zypper install -y git curl jq help2man pandoc

Optional: set up a local AI model with Ollama (recommended for privacy/offline use):

curl -fsSL https://ollama.com/install.sh | sh
sudo systemctl enable --now ollama 2>/dev/null || true
# Pull a small, capable model
ollama pull llama3.2
# Quick test
ollama run llama3.2 "Summarize: echo says hello"

Optional: use a hosted provider (e.g., OpenAI). Export your key:

export OPENAI_API_KEY="sk-..."

---

1) Add a single ask_ai() function your scripts can call

Create a light abstraction that prefers local models (Ollama) and falls back to a hosted API if configured.

# ai.sh
ask_ai() {
  local prompt="$1"
  if command -v ollama >/dev/null 2>&1; then
    # OLLAMA_MODEL can be overridden; default to llama3.2
    local model="${OLLAMA_MODEL:-llama3.2}"
    ollama run "$model" "$prompt"
  elif [ -n "${OPENAI_API_KEY:-}" ]; then
    curl -s https://api.openai.com/v1/chat/completions \
      -H "Authorization: Bearer $OPENAI_API_KEY" \
      -H "Content-Type: application/json" \
      -d "$(jq -n --arg p "$prompt" \
        '{"model":"gpt-4o-mini","messages":[{"role":"user","content":$p}],"temperature":0.2}')" \
    | jq -r '.choices[0].message.content'
  else
    echo "No AI backend configured (install Ollama or set OPENAI_API_KEY)." >&2
    return 1
  fi
}

Source it in your scripts:

. ./ai.sh

Tip:

• Keep prompts short, provide concrete inputs (help/man/code), and ask for structured outputs (Markdown).

---

2) Auto-generate CLI docs from --help and man pages

Turn raw command help into readable Markdown docs. Prefer deterministic tools (help2man + pandoc), then optionally refine with AI.

# gen-cli-docs.sh
#!/usr/bin/env bash
set -euo pipefail
. ./ai.sh

OUT="${OUT_DIR:-docs/cli}"
mkdir -p "$OUT"

for cmd in "$@"; do
  if ! command -v "$cmd" >/dev/null 2>&1; then
    echo "Skip $cmd (not found)"
    continue
  fi

  # Capture --help and version for grounding
  { "$cmd" --help 2>&1 || "$cmd" -h 2>&1 || true; } > "$OUT/$cmd.help.txt"
  { "$cmd" --version 2>&1 || "$cmd" -V 2>&1 || true; } > "$OUT/$cmd.version.txt"

  if command -v help2man >/dev/null 2>&1 && command -v pandoc >/dev/null 2>&1; then
    # Create a man page; -N: no include of "This is free software..."
    help2man -N "$cmd" -o "$OUT/$cmd.1" || true
    if [ -s "$OUT/$cmd.1" ]; then
      pandoc -f man -t gfm "$OUT/$cmd.1" -o "$OUT/$cmd.md"
    else
      ask_ai "Convert this CLI help to concise Markdown with examples. Command: $cmd

$(
  sed -e '1,200p' "$OUT/$cmd.help.txt"
)" > "$OUT/$cmd.md" || cp "$OUT/$cmd.help.txt" "$OUT/$cmd.md"
    fi
  else
    ask_ai "Convert this CLI help to concise Markdown with examples. Command: $cmd

$(
  sed -e '1,200p' "$OUT/$cmd.help.txt"
)" > "$OUT/$cmd.md" || cp "$OUT/$cmd.help.txt" "$OUT/$cmd.md"
  fi

  echo "Wrote $OUT/$cmd.md"
done

Usage:

bash gen-cli-docs.sh tar grep awk

What you get:

• Deterministic Markdown from man where possible.

• AI-polished docs when man generation fails, grounded in real --help.

---

3) Generate a README from Bash comments + -h output

Leverage what you already maintain: top-of-file comments, function names, and -h/--help. AI stitches this into a user-friendly README.

# readme_from_comments.sh
#!/usr/bin/env bash
set -euo pipefail
. ./ai.sh

SCRIPT="${1:-}"
[ -n "$SCRIPT" ] || { echo "Usage: $0 path/to/script.sh" >&2; exit 1; }
[ -f "$SCRIPT" ] || { echo "Not found: $SCRIPT" >&2; exit 1; }

TMP="$(mktemp -d)"
trap 'rm -rf "$TMP"' EXIT

# Extract leading comment block
awk 'NR==1{b=1} b && /^#/ {sub(/^# ?/,""); print; next} b && !/^#/ {b=0}' "$SCRIPT" > "$TMP/comments.txt"

# Try to get help text
HELP_OUT="$({ bash "$SCRIPT" -h 2>&1 || bash "$SCRIPT" --help 2>&1 || true; })"
printf "%s" "$HELP_OUT" > "$TMP/help.txt"

# Grab function headers
grep -nE '^[[:space:]]*[a-zA-Z_][a-zA-Z0-9_]*[[:space:]]*\(\)[[:space:]]*\{' "$SCRIPT" \
  | sed -E 's/\s*\{.*$//' > "$TMP/funcs.txt" || true

PROMPT=$(cat <<'EOF'
You are producing a README.md for a Bash CLI tool.
Requirements:

- Start with a one-paragraph overview (what, why).

- Show install/prereqs if any.

- Include Usage, Options, and at least 3 concrete examples.

- List environment variables and exit codes if provided.

- Keep strictly to provided help/comments—do not invent flags.

SOURCE: COMMENTS
EOF
)
PROMPT="$PROMPT
$(cat "$TMP/comments.txt")

SOURCE: HELP
$(cat "$TMP/help.txt")

SOURCE: FUNCTIONS
$(cat "$TMP/funcs.txt")
"

ask_ai "$PROMPT" > README.md
echo "Generated README.md from $SCRIPT"

Usage:

bash readme_from_comments.sh ./mytool.sh

Tip:

• Maintain a clean, accurate -h/--help. That’s your ground truth.

---

4) Make it automatic with a Git pre-commit hook

Regenerate docs whenever you commit. If docs change, they’ll be staged with the commit.

# .git/hooks/pre-commit (make it executable)
#!/usr/bin/env bash
set -e

# Rebuild docs
[ -x ./gen-cli-docs.sh ] && ./gen-cli-docs.sh ./mytool.sh
[ -x ./readme_from_comments.sh ] && ./readme_from_comments.sh ./mytool.sh

# Stage updated docs
git add docs README.md 2>/dev/null || true

Enable:

chmod +x .git/hooks/pre-commit

Optional Makefile target:

docs:
    ./gen-cli-docs.sh ./mytool.sh
    ./readme_from_comments.sh ./mytool.sh

---

5) AI-assisted changelog from git history

Summarize commits since the last tag into a human-friendly, categorized changelog draft.

# ai-changelog.sh
#!/usr/bin/env bash
set -euo pipefail
. ./ai.sh

LAST_TAG="$(git describe --tags --abbrev=0 2>/dev/null || true)"
if [ -n "$LAST_TAG" ]; then
  LOG=$(git log --pretty=format:'- %s (%h) by %an on %ad' --date=short "${LAST_TAG}..HEAD")
else
  LOG=$(git log --pretty=format:'- %s (%h) by %an on %ad' --date=short)
fi

PROMPT=$(cat <<EOF
Create a "Keep a Changelog" compliant release note from the commit list below.

- Group by feat, fix, perf, docs, refactor, build, chore.

- Note BREAKING CHANGES if present.

- Keep it concise and accurate; do not invent changes.

COMMITS:
$LOG
EOF
)

ask_ai "$PROMPT" > CHANGELOG_PENDING.md
echo "Wrote CHANGELOG_PENDING.md (review and merge into CHANGELOG.md)"

Usage:

bash ai-changelog.sh

---

Real-world example: from --help to Markdown

Imagine backup.sh -h outputs flags for source, destination, compression, and retention. Running:

bash gen-cli-docs.sh ./backup.sh

produces docs/cli/backup.sh.md with:

• A clear summary

• Option table (or bullet list)

• 3–5 ready-to-copy examples (e.g., daily cron usage, dry-run, restore path)

• Exit codes and failure scenarios

This beats a wall of --help for most users—and it stays in sync every time you commit.

---

Guardrails and good practices

• Always ground AI with real inputs: --help, man pages, comments, and git logs.

• Keep prompts short and specific; ask for Markdown with examples.

• Review outputs, especially the first time or after large changes.

• Prefer local models for private or regulated environments (Ollama).

• Store generated docs in-repo; treat them like build artifacts that must compile.

---

Conclusion and Call To Action

Documentation should evolve at the speed of your CLI—not lag behind it. You now have:

• A drop-in ask_ai() function (local or cloud)

• Scripts to turn --help into Markdown

• A README generator from comments and help

• A pre-commit hook to keep docs fresh

• A changelog summarizer from git history

Your next steps: 1) Install prerequisites and set up Ollama or your API key.
2) Drop ai.sh, gen-cli-docs.sh, readme_from_comments.sh, and ai-changelog.sh into your repo.
3) Wire make docs and the pre-commit hook.
4) Run it on one CLI today and ship better docs by end of day.

If you found this useful, automate one internal tool right now—then share the before/after with your team. Your future self (and your users) will thank you.