Commands
Every pgdba command and its purpose.
| Command | Purpose | Writes? |
|---|---|---|
pgdba check |
Run read-only health checks; print ranked findings; write pgdba-report.md/.json |
reports only (with --state-dir) |
pgdba check --apply |
Execute remediation SQL you approve, per action | yes, gated |
pgdba migrate |
Server-to-server migration: preflight → confirm → copy → verify | yes, gated |
pgdba migrate --plan-only |
Dry-run: preflight + planning, zero target writes | no (report only) |
pgdba why <finding-id> |
Plain-language explainer for one finding from the last report | no |
pgdba baseline save/show/clear/update |
Accept, list, re-accept, or drop the drift baseline (ids + severities) | baseline file only |
pgdba check --journal |
Append a zero-write audit line for the run to pgdba-audit.jsonl |
journal file only |
pgdba audit show |
Print the zero-write audit trail | no |
pgdba self-scan [--dsn URL] |
Scan pgdba’s own artifacts for secret residue; with a DSN also probe the read-only contract | no (temp tables refused/dropped) |
pgdba checks list |
Print the check catalog (duty, data requirements, PG support); --format json for agents |
no |
pgdba fix <finding-id> |
Build an ordered, reversible fix plan from the last report (dry-run default; --apply/--revert execute) |
scripts only (gated writes with --apply/--revert) |
pgdba fleet check |
Check every fleet target; per-target reports plus aggregate fleet-report.json/.md |
reports only |
pgdba serve [--once] |
Scheduled checks per target plus a read-only local JSON API (--once: one pass, no HTTP) |
reports/history only |
pgdba check --fail-on-drift new|resolved|any |
Exit 1 on baseline drift of that class, independent of thresholds | no |
pgdba verify-restore |
Verify a backup repository; --restore rehearses into scratch scratch |
scratch only, fenced |
pgdba config |
Print personalized config proposals from live signals | no |
pgdba config init |
Probe a connection and write a starter pgdba-run.toml |
writes the config file |
pgdba config doctor |
Validate the config and probe every profile | no |
pgdba check --explain-term <term> |
Print a glossary entry and exit | no |
pgdba check --explain-flag <name> |
Print a flag/config-key entry (with its safe default) and exit | no |
Flag lookup from the terminal
pgdba check --explain-flag pooled # what/when/safe default
pgdba check --explain-term "duty group" # report vocabulary
Misspellings suggest the closest match (--explain-flag state-dir →
did you mean: state_dir?) and exit 3 without printing a wrong entry.
Full option listings live in pgdba <command> --help; the
flags & config keys reference documents
the high-traffic set with safe defaults.
Agent output
Every command can emit one strict-JSON document on stdout for AI agents instead of the rich human rendering — activation, per-command fields, and output guarantees: agent output.