Agent output

One strict-JSON document per command for AI agents — activation, fields, guarantees.

Every command can emit one compact JSON document on stdout for AI agents (Claude Code, Cursor, Gemini CLI, Devin, …) instead of the rich human rendering — same information, a fraction of the tokens, no decoration to parse.

Activate it any of three ways; the human output never changes unless one of these is active:

pgdba --agent check --dsn "$DATABASE_URL"   # explicit flag
PGDBA_AGENT=1 pgdba check ...               # environment
pgdba --no-agent check ...                  # force human output

Auto-detection: PGDBA_AGENT=1, or a detected agent environment (CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, CURSOR_AGENT, GEMINI_CLI, AGENT, DEVIN_*). --no-agent always wins.

The JSON carries the command name, the real exit code, compact result fields, and the paths of artifacts written — details stay in the artifact files (pgdba-report.json, migrate-report.json, pgdba-config.json) which agents can open on demand:

{"command": "check", "exit_code": 1, "critical": 0, "warning": 4,
 "info": 22, "skipped": 0, "grade": "C", "evidence_quality": "full",
 "top_ids": ["config.work_mem", "config.checkpoint"],
 "report_json": "pgdba-report.json", "report_markdown": "pgdba-report.md",
 "webhook_delivery": null}

Per-command fields: check (severity counts, grade, top ids, drift ids when a baseline exists, artifact paths; --explain-flag returns explain_flag + explanation), config (top proposals with suggested SQL), config init (profile, config path, ready-to-run next_step), config doctor (per-profile ok/latency/error), migrate (phase, engine, downtime estimate, success flags; preflight refusals carry check/detail/remediation), verify-restore (verified/restored, RTO verdict, issues), why (finding id, severity, full explanation text), baseline (action, finding map with run provenance for show), audit (action, run lines), self-scan (clean verdict, per-sink hits, contract block), checks list (schema version, checksum, full catalog entries), fix (finding id, mode, manual flag, plan statements, artifact paths), fleet (per-target rows, fleet-common rollup, aggregate artifact paths), serve --once (per-target rows, fleet-common rollup).

Guarantees: stdout is exactly one strict-JSON document in agent mode — logs go to stderr as JSON lines; ANSI, tables, box-drawing, and trailing summary lines never touch stdout; exit codes are identical to human mode in every case.