docs: add automation examples

docs/automation-examples.md

@@ -0,0 +1,128 @@
+# Automation Examples
+
+These examples are intended as starting points for local scripts and
+infrastructure automation. They assume the single `geth` executable is on
+`PATH`.
+
+## Shell
+
+Initialize a home, start the daemon in a user-owned process, wait for control,
+and read stable JSON status:
+
+```sh
+#!/usr/bin/env sh
+set -eu
+
+export GETH_HOME="${GETH_HOME:-$HOME/.local/share/geth/geth}"
+
+geth init
+geth daemon run >"$GETH_HOME/daemon.log" 2>&1 &
+daemon_pid=$!
+
+geth wait daemon --timeout-ms 30000
+geth doctor --json
+geth status --json
+
+trap 'kill "$daemon_pid" 2>/dev/null || true' EXIT
+```
+
+Create a backup into a separate directory and validate that it can restore to a
+new home:
+
+```sh
+#!/usr/bin/env sh
+set -eu
+
+backup_dir="${1:?backup dir required}"
+restore_home="$(mktemp -d)"
+
+geth backup create --out "$backup_dir"
+geth backup restore "$backup_dir" --target-home "$restore_home"
+GETH_HOME="$restore_home" geth doctor --json || true
+```
+
+## Python JSON
+
+Use CLI JSON output without parsing human text:
+
+```python
+#!/usr/bin/env python3
+import json
+import os
+import subprocess
+import sys
+
+
+def geth(*args, check=True):
+    proc = subprocess.run(
+        ["geth", "--json", *args],
+        check=False,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=os.environ.copy(),
+    )
+    if check and proc.returncode != 0:
+        raise RuntimeError(proc.stderr or proc.stdout)
+    return json.loads(proc.stdout)
+
+
+doctor = geth("doctor", check=False)
+for check in doctor["checks"]:
+    print(check["status"], check["code"], check["message"])
+
+status = geth("status")
+print(status["node_id"], status.get("endpoint_id"))
+```
+
+Wait for a known peer before pulling sync status:
+
+```python
+#!/usr/bin/env python3
+import json
+import subprocess
+import sys
+
+node = sys.argv[1]
+
+wait = subprocess.run(
+    ["geth", "--json", "wait", "peer", node, "--timeout-ms", "30000"],
+    text=True,
+    stdout=subprocess.PIPE,
+)
+report = json.loads(wait.stdout)
+if not report["ready"]:
+    raise SystemExit(report["reason"])
+
+sync = subprocess.check_output(["geth", "--json", "sync", "status"], text=True)
+print(sync)
+```
+
+## User Service
+
+Install and operate the daemon through the current user's service manager. These
+commands do not install a system service and do not require privileged service
+manager mutation:
+
+```sh
+geth daemon service print
+geth daemon service install --start
+geth wait daemon --timeout-ms 30000
+geth daemon service status
+geth daemon service stop
+geth daemon service uninstall
+```
+
+Admin SSH keys remain outside geth state. Automation should pass public admin
+keys with `--admin-key` and use the matching private key only as an argument to
+the explicit signing command when an admin operation is intended:
+
+```sh
+geth init \
+  --admin-key "$HOME/.ssh/id_ed25519.pub" \
+  --signing-key "$HOME/.ssh/id_ed25519" \
+  --node-name "$(hostname)"
+```
+
+Do not copy private SSH admin keys into `GETH_HOME`, backups, service
+definitions, or shared project repositories.