diff --git a/README.md b/README.md index c40af94..3cb4c88 100644 --- a/README.md +++ b/README.md @@ -269,6 +269,7 @@ hostname. Run a read-only health snapshot from the Debian server with: ```bash +./jeannie help ./jeannie status ./jeannie capacity ./jeannie recover-plan @@ -289,6 +290,10 @@ Run a read-only health snapshot from the Debian server with: ./jeannie map ``` +`help` prints the grouped command reference in pipeline order, from inventory +and bootstrap through cluster lifecycle, reports, observability, recovery, +access, apps, security, AI, and destructive commands. + It reports host memory/disk, systemd services, Docker Compose stacks, Kubernetes health when the API is reachable, Pimox worker VM status, RPi services, Tailscale, key local/public HTTP endpoints, and "what broke" signals diff --git a/README.md.tmpl b/README.md.tmpl index c619506..372b10d 100644 --- a/README.md.tmpl +++ b/README.md.tmpl @@ -269,6 +269,7 @@ hostname. Run a read-only health snapshot from the Debian server with: ```bash +./{{ main_script }} help ./{{ main_script }} status ./{{ main_script }} capacity ./{{ main_script }} recover-plan @@ -289,6 +290,10 @@ Run a read-only health snapshot from the Debian server with: ./{{ main_script }} map ``` +`help` prints the grouped command reference in pipeline order, from inventory +and bootstrap through cluster lifecycle, reports, observability, recovery, +access, apps, security, AI, and destructive commands. + It reports host memory/disk, systemd services, Docker Compose stacks, Kubernetes health when the API is reachable, Pimox worker VM status, RPi services, Tailscale, key local/public HTTP endpoints, and "what broke" signals diff --git a/docs/jeannie.1.md b/docs/jeannie.1.md index d0b408f..40cd397 100644 --- a/docs/jeannie.1.md +++ b/docs/jeannie.1.md @@ -23,8 +23,17 @@ The canonical script name is `metadata.main_script` in `homelab.yml`. ## COMMANDS +Run `./jeannie help` for the short in-terminal command reference. It is grouped +in the same order as the pipeline: inventory and planning, bootstrap, cluster +lifecycle, reports, observability, recovery, doctors, access, apps, security, +AI, and destructive commands. + ### Core Lifecycle +`help` +: Print the grouped command reference. The same output is shown for `-h`, +`--help`, or no command. + `up` : Deploy the full homelab pipeline. Runs early preflight, deploys Gitea and RPi services, runs full preflight and pre-apply doctor checks, then applies Pimox, diff --git a/jeannie b/jeannie index 06bfd1b..5d89c76 100755 --- a/jeannie +++ b/jeannie @@ -6052,7 +6052,112 @@ homelab_map() { "${REPO_ROOT}/scripts/homelab-map" "${@:2}" } +print_usage() { + cat <<'EOF' +Usage: ./jeannie [args] + +Base, Inventory, And Planning + help | -h | --help Show this grouped help. + validate Run repo validation checks. + inventory-check Validate the canonical homelab inventory. + preflight Run non-mutating infrastructure preflight checks. + doctor-preapply Run deeper pre-apply safety checks. + plan [all|provisioning|cluster|platform|apps|edge] + Run OpenTofu plans without applying changes. + +Build And Bootstrap + up Deploy the full homelab pipeline. + deploy-gitea Deploy the Debian-hosted Gitea container. + bootstrap-gitea-repo Ensure the Gitea repo and SSH key wiring exist. + rpi-services Deploy Pi-hole, Unbound, and Uptime Kuma on RPi4. + ollama-setup Install/configure Ollama on the Debian host. + artifact-cache {status|up|down|instructions} + Manage optional Debian artifact caches. + golden-ledger {show|check} Show or validate Pimox golden image versions. + +Cluster Lifecycle + rebuild-cluster Recreate the cluster through the guarded path. + stop-cluster Stop Kubernetes and worker VMs without destroy. + start-cluster Start Kubernetes and desired worker VMs. + workers + Manage Pimox/Kubernetes workers. + move-prometheus-stack-workers Move monitoring workloads to worker nodes. + doctor-versions Check Kubernetes/container tooling versions. + +Operator View And Reports + status Cascading health check from host to public URLs. + scorecard Compact pass/warn/fail operator scorecard. + capacity Compact capacity and placement report. + recover-plan Print disaster recovery order and prerequisites. + recover-power [--dry-run] Run or preview post-outage recovery. + map [--dot] Print the homelab dependency map. + change-journal {list|path} Show risky-command journal entries. + release-snapshot Write a pre-change release snapshot. + +Observability And GitOps + grafana-dashboards {list|apply} List or apply repo-managed Grafana dashboards. + gitops-status Print focused Argo CD health and sync status. + cert-check Check public DNS, TLS, and edge URL health. + backup-status Check backup and restore-drill freshness. + synthetic-checks Run end-to-end service probes. + resource-budget Report Kubernetes resource request/limit gaps. + route-inventory Report routes and Uptime Kuma coverage. + +Recovery And State + backup-gitea Back up the Debian-hosted Gitea data. + drill-restore Run all restore drills. + drill-gitea-restore Run the Gitea restore drill. + drill-pihole-restore Run the Pi-hole restore drill. + state-backup Back up local OpenTofu state files. + +Focused Doctors + doctor-edge Diagnose edge routing and public exposure. + doctor-gitea Diagnose Gitea local/public access. + doctor-rpi Diagnose RPi services and DNS. + doctor-cluster Diagnose Kubernetes cluster health. + +Access, Secrets, And Policy + access-audit Audit SSH, Gitea, Kubernetes, and Tailscale access. + kubeconfig-readonly Create/check read-only kubeconfig material. + secrets-init Initialize SOPS/age secret tooling. + secrets-check Validate repo-managed secret prerequisites. + tailnet-policy-check Validate Tailscale ACL policy as code. + fix-debian-docker-root Repair Debian Docker root placement. + +Apps And Services + apps Deploy application stack only. + website-translation-model Prepare website translation model support. + website-ollama-listen Configure website Ollama access. + install-gitea-runner [TOKEN] Install the Gitea Actions runner. + openwrt Deploy/check OpenWrt lab config. + +Security Learning + security-scan Run the security scan bundle. + security-prepare Prepare defensive security tools. + security-zap Run OWASP ZAP checks. + security-k8s Run Kubernetes security checks. + security-host Run host security checks. + security-trivy Run Trivy scans. + security-secrets Run secret leak checks. + security-nuclei Run Nuclei web checks. + security-web Run web security checks. + security-logs Review security-relevant logs. + security-runtime Check runtime security sensors. + security-attack-path Print prioritized attack-path findings. + +AI And Indexing + ai-index Build the local homelab RAG index. + ai-check Query/check the local AI index. + +Destructive + nuke Guarded cluster state destruction path. +EOF +} + case "${1:-}" in + "" | help | -h | --help) + print_usage + ;; up) record_change_journal "up" "$@" up @@ -6275,7 +6380,8 @@ case "${1:-}" in echo "Log: ${JEANNIE_LOG_FILE}" ;; *) - echo "Usage: $0 {up|plan [all|provisioning|cluster|platform|apps|edge]|rebuild-cluster|stop-cluster|start-cluster|status|capacity|recover-plan|recover-power [--dry-run]|scorecard|gitops-status|cert-check|release-snapshot|backup-status|synthetic-checks|resource-budget|artifact-cache {status|up|down|instructions}|golden-ledger {show|check}|route-inventory|grafana-dashboards {list|apply}|workers |change-journal {list|path}|map [--dot]|validate|access-audit|kubeconfig-readonly|apps|website-translation-model|website-ollama-listen|ollama-setup|deploy-gitea|rpi-services|bootstrap-gitea-repo|backup-gitea|drill-restore|drill-gitea-restore|drill-pihole-restore|install-gitea-runner|move-prometheus-stack-workers|doctor-versions|doctor-edge|doctor-gitea|doctor-rpi|doctor-cluster|preflight|doctor-preapply|inventory-check|state-backup|fix-debian-docker-root|secrets-init|secrets-check|tailnet-policy-check|ai-index|ai-check|security-scan|security-prepare|security-zap|security-k8s|security-host|security-trivy|security-secrets|security-nuclei|security-web|security-logs|security-runtime|security-attack-path|openwrt|nuke}" + printf 'Unknown command: %s\n\n' "$1" >&2 + print_usage >&2 exit 1 ;; esac