CLI Reference

Every hasteward command and flag, generated from the CLI itself — never hand-edited. The same content is available at the terminal via hasteward <command> --help.

HASteward safely triages, repairs, backs up, and restores database clusters managed by CNPG (PostgreSQL) and MariaDB Operator (Galera).

Backups are stored in restic repositories with block-level dedup, encryption, and compression.

Global Flags

Flag	Type	Default	Description
--backups-path	string	``	Restic repository path or URL
--cluster, -c	string	``	Database cluster CR name
--debug	bool	false	Enable debug output
--delete-timeout	int	300	Delete wait timeout in seconds
--donor, -d	string	``	Explicit donor instance ordinal (declares authoritative source for repair)
--dry-run	bool	false	Show planned actions without executing (destructive commands)
--engine, -e	string	``	Database engine: cnpg or galera
--fix-bootstrap	bool	false	Reconfigure: clear grastate and remove bootstrap config on target instance. Prevents stale local bootstrap behavior during cluster restart.
--force, -f	bool	false	Override automatic safety refusal for targeted repair. In ambiguous Galera recovery states (divergent UUIDs, split-brain, no clear primary), --donor is required to declare the authoritative source node.
--heal-timeout	int	600	Heal wait timeout in seconds
--instance, -i	string	``	Target specific instance number
--kubeconfig	string	``	Path to kubeconfig file
--method, -m	string	dump	Backup method: dump or native
--namespace, -n	string	``	Kubernetes namespace
--no-color	bool	false	Disable color output
--no-escrow	bool	false	Skip pre-repair escrow backup
--output	string	auto	Output format: auto, human, json, jsonl
--restic-password	string	``	Restic repository encryption password
--snapshot	string	latest	Restic snapshot ID or 'latest' (for restore)
--unwedge	bool	false	CNPG deadlock breaker: clear a disposable replica's datadir offline (escrow-gated) to un-freeze a disk-full cluster. Use --dry-run first.
--verbose, -v	bool	false	Verbose output (debug logging)
--wipe-datadir	bool	false	Wipe entire datadir on target instance (not just grastate). Forces full SST reseed from donor. Use when local data is irrecoverably corrupted. Requires --force and --instance.

Commands

hasteward backup

Back up a database cluster

Usage: hasteward backup

hasteward bootstrap

Bootstrap a fully-down Galera cluster from the best candidate

Performs a full Galera cluster bootstrap when ALL nodes are down.

This is a DANGEROUS operation. It identifies the node with the highest
sequence number (most recent data), sets safe_to_bootstrap=1, patches
the MariaDB CR with forceClusterBootstrapInPod, and brings the cluster
back from total failure.

Safety gates:
  - Refuses if any healthy nodes exist (use 'repair' instead)
  - Refuses if seqno is ambiguous across nodes (unless --force)
  - Refuses if split-brain is detected (unless --force)
  - Supports --dry-run to preview the plan without mutation

Use --dry-run --output json for automation to inspect the decision
before approving execution.

Examples:
  hasteward bootstrap -e galera -c kimai-mariadb -n hyrule-castle
  hasteward bootstrap -e galera -c kimai-mariadb -n hyrule-castle --dry-run
  hasteward bootstrap -e galera -c kimai-mariadb -n hyrule-castle --dry-run --output json
  hasteward bootstrap -e galera -c kimai-mariadb -n hyrule-castle --force

Usage: hasteward bootstrap

hasteward docs

Documentation generation commands

Usage: hasteward docs [flags]

hasteward docs generate

Generate reference documentation fragments from code

Generate reference documentation as markdown fragments — one per registered
generator (cli-reference, env-reference, ...) — into --output-dir. The fragments are
assembled into the docs site's reference pages by the pipeline's narrate step.

Run against the freshly-built binary so the output reflects the CLI and environment
bindings actually being shipped, never a stale copy.

Usage: hasteward docs generate [flags]

Flag	Type	Default	Description
--help, -h	bool	false	help for generate
--output-dir	string	docs/assets/modules	output directory for generated fragments

hasteward export

Extract a backup snapshot to a local .sql.gz file

Exports a database dump from a restic snapshot to a local gzipped SQL file.

For diverged snapshots, use -i to specify the instance ordinal.

Examples:
  hasteward export -e cnpg -c zitadel-postgres -n zeldas-lullaby --snapshot latest -o dump.sql.gz
  hasteward export -e cnpg -c zitadel-postgres -n zeldas-lullaby --snapshot abc123 -i 2 -o instance2.sql.gz

Usage: hasteward export [flags]

Flag	Type	Default	Description
--file, -o	string	``	Output file path (e.g., dump.sql.gz)

hasteward get

Display resources (backups, policies, repositories, status)

Usage: hasteward get

Flag	Type	Default	Description
--all-namespaces, -A	bool	false	List across all namespaces
--type, -t	string	all	Snapshot type filter: backup, diverged, or all

hasteward get backups

List restic backup snapshots

Usage: hasteward get backups

hasteward get policies

List BackupPolicy resources

Usage: hasteward get policies

hasteward get repositories

List BackupRepository resources

Usage: hasteward get repositories

hasteward get status

Show triage status of managed database clusters

Usage: hasteward get status

hasteward prune

Remove stale data (backups, WAL)

Prune commands for cleaning up accumulated data.

Available subcommands:
  backups    Apply retention policy and remove old backup snapshots
  wal        Clear accumulated WAL from a disk-full CNPG instance

Usage: hasteward prune

hasteward prune backups

Apply retention policy and remove old backup snapshots

Prunes old backup snapshots from restic repositories according to the
configured retention policy (keep-last, keep-daily, keep-weekly, keep-monthly).

By default, only type=backup snapshots are pruned. Use -t diverged to prune
only diverged snapshots, or -t all to prune both types.

For diverged snapshots, retention is group-aware: snapshots sharing the same
job tag (from one repair operation) are kept or removed as a unit. So
--keep-last 3 means "keep the 3 most recent repair jobs" regardless of how
many instances each job captured.

Examples:
  hasteward prune backups -e cnpg -c zitadel-postgres -n zeldas-lullaby --backups-path /backups
  hasteward prune backups -e cnpg -c zitadel-postgres -n zeldas-lullaby --backups-path /backups \
    --keep-last 7 --keep-daily 30 --keep-weekly 12 --keep-monthly 24
  hasteward prune backups -e cnpg -c zitadel-postgres -n zeldas-lullaby --backups-path /backups \
    -t diverged --keep-last 3

Usage: hasteward prune backups [flags]

Flag	Type	Default	Description
--keep-daily	int	30	Keep N daily snapshots (or jobs for diverged)
--keep-last	int	7	Keep the last N snapshots (or jobs for diverged)
--keep-monthly	int	24	Keep N monthly snapshots (or jobs for diverged)
--keep-weekly	int	12	Keep N weekly snapshots (or jobs for diverged)
--type, -t	string	backup	Snapshot type to prune: backup, diverged, or all

hasteward prune wal

Clear accumulated WAL from a disk-full CNPG instance

Clears accumulated WAL segments from a disk-full PostgreSQL primary.

This is a DESTRUCTIVE operation. It deletes WAL files from the instance's
PVC to free disk space when the primary is stuck in a WAL-accumulation
deadlock (disk full -> can't start -> replicas can't connect -> replication
slots hold WAL -> disk stays full).

Safety: Only operates on CNPG clusters. Requires --instance to target a
specific instance. Runs triage first to verify cluster state. Refuses to
proceed if no healthy replicas exist.

Flow: triage -> safety check -> fence -> mount PVC -> clear pg_wal -> unfence

Examples:
  hasteward prune wal -e cnpg -c nextcloud-postgres -n temple-of-time -i 2
  hasteward prune wal -e cnpg -c grafana-postgres -n gossip-stone -i 1

Usage: hasteward prune wal

hasteward reconfigure

Cluster-scoped authority correction (stops all pods, fixes metadata, restarts)

Reconfigure performs cluster-scoped authority correction on a Galera cluster.
This operation intentionally stops all database pods, modifies authority
metadata on the target instance, and restarts the cluster.

This is NOT repair (instance-scoped). This is a cluster restart with
corrected metadata. All nodes will experience downtime.

Requires --force, --instance, and at least one action flag (--fix-bootstrap).

Usage: hasteward reconfigure

hasteward repair

Heal unhealthy database instances

Usage: hasteward repair

hasteward restore

Restore a database cluster from a restic snapshot

Usage: hasteward restore

hasteward serve

Run the hasteward operator (controller + scheduler)

Starts the hasteward operator which watches CNPG Cluster and MariaDB CRs
for clinic.hasteward.prplanit.com/policy annotations and automatically runs scheduled backups
and triage/repair operations based on BackupPolicy configuration.

Endpoints:
  :8080/metrics   Prometheus metrics
  :8081/healthz   Liveness probe
  :8081/readyz    Readiness probe

Usage: hasteward serve

hasteward triage

Read-only diagnostics for a database cluster

Usage: hasteward triage