Skip to content

KH3 CLI

Updated: 2026-06-26

scripts/kh3 is the repository-native entrypoint for repeated KH3 infrastructure operations. It starts with read-only status checks, validation wrappers, and local rootless Podman service scaffolding for the current OPNsense, Technitium, Caddy, and Podman LXC architecture.

Run it from the repository root:

scripts/kh3 help

Safety Rules

The CLI must not print env files, Caddy data, Technitium config or backups, OPNsense exports, app.ini, private keys, or staged backup contents.

Remote status and validation commands are read-only. The service scaffold command writes only to the local repository under generated/podman-services/; it does not install files into CT 101.

Commands

Command Purpose
scripts/kh3 help Show commands, scaffold options, and safety notes.
scripts/kh3 dr status Summarize Proxmox VMs/CTs, CT 101 rootless Podman state, CT 103 Caddy version/modules/listeners, and CT 102 DNS listeners.
scripts/kh3 podman validate Run scripts/podman/05-validate-rootless-services.sh inside CT 101 through Proxmox.
scripts/kh3 podman scaffold-service NAME --image IMAGE [options] Generate a local rootless Quadlet scaffold for review.
scripts/kh3 caddy validate Load Caddy env inside CT 103 without printing it, validate the Caddyfile, and list selected modules.
scripts/kh3 dns validate Query Technitium at 192.168.2.2 for the core internal records and public recursion.

Podman Service Scaffolds

Example:

scripts/kh3 podman scaffold-service demo \
  --image docker.io/library/nginx:alpine \
  --container-port 80 \
  --host-port 30090

Generated files:

generated/podman-services/demo/
  demo.container
  demo.env.example
  README.md

The generated Quadlet follows the rootless CT 101 service standard:

  • Network=kh3-backend.network
  • EnvironmentFile=/opt/podman/env/NAME.env
  • Volume=/opt/podman/volumes/NAME:/data by default
  • high-port PublishPort only when requested
  • no low host ports
  • no secrets in generated files
  • PostgreSQL ordering only when --requires-postgres is passed

The command refuses invalid service names, missing images, host ports below 1024, and existing generated service directories unless --force is used.

DNS Validation

scripts/kh3 dns validate uses local dig when available. If the workstation does not have dig, it runs the same checks through CT 102.

Records checked:

  • git.kh3group.com
  • pass.kh3group.com
  • dbgui.kh3group.com
  • example.com