Command reference

Every PETROVA CLI command, with synopsis, flags, and exit codes.

Conventions

• <repo> is a slug from registry.yaml.
• All commands accept --json for machine-readable output.
• Write commands accept --input <path> (reads JSON from file) and --apply (without it, runs dry-run).
• Exit codes:
  • 0 — success
  • 1 — verb returned failed status, or write verb hit a constraint violation
  • 2 — auth missing on --apply, or unrecoverable error

Read commands

petrova status [--repo <slug>...]

Cross-repo summary table.

Flags:

• --repo <slug>... — filter to specific repos
• --json — emit raw JSON

Output (table): slug, role, profile, local-presence, phase, open milestones, recent decisions.

petrova diagnose <repo>

Single-repo deep dive. Returns a diagnosis_id other verbs (propose_fix) can bind to within 24h.

Flags:

• --scope <scope> — full (default) | phase | decisions | findings | ci
• --since <iso> — lower bound for time-windowed sections (default: 30d ago)
• --actor <actor> — actor identifier (default: human:cli)
• --json — emit raw JSON

petrova validate <repo>

MR / convention compliance check. Outputs findings grouped by rule (MR-4, MR-6, MR-7, MR-12).

Flags:

• --json — emit raw JSON

Exit: non-zero if any error-severity finding.

petrova dashboard

Cross-repo aggregator with grouping, totals, warnings.

Flags:

• --repo <slug>... — filter
• --group-by <axis> — role (default) | profile | none
• --format <fmt> — table (default) | markdown | json

petrova verbs

Lists known verb names from spec/verbs/. Useful for sanity-check after install.

Write commands

All write commands share the same surface:

petrova <verb> <repo> [--input <path>]
                      [--actor <actor>]
                      [--triggered-by-kind <kind>]
                      [--triggered-by-ref <ref>]
                      [--apply]
                      [--json]

If --input is omitted, JSON params are read from stdin. --apply is required to emit a PR — without it, dry-run.

The eight write verbs:

Verb	Upholds	One-line use
open_decision	MR-4, MR-7	Record a non-trivial decision.
update_milestone	MR-2, MR-7	Add / transition a milestone.
start_phase	MR-2, MR-7, MR-10	Open Phase N.
close_phase	MR-2, MR-7, MR-10	Close Phase N (after verify_round).
verify_round	MR-10	Mandatory verification round at phase close.
request_review	MR-3, MR-12	Generic file-change PR.
request_merge_when_green	MR-3, MR-12	Auto-merge variant (profile-restricted).
propose_fix	MR-7, MR-12	Fix grounded in a recent diagnose.

Per-verb input shapes are at the verb reference.

Examples

# Read-only round trip
petrova status
petrova diagnose kahn-hq --since 2026-04-01
petrova validate kahn-hq

# Dry-run a decision
echo '{"title":"x","slug":"x","context":"x","decision":"x","alternatives_considered":[{"name":"a","rejection_reason":"b"},{"name":"c","rejection_reason":"d"}]}' \
  | petrova open_decision petrova-hq

# Dashboard as markdown for paste
petrova dashboard --format markdown

# Apply (requires PETROVA_GITHUB_TOKEN)
petrova open_decision petrova-hq --input /tmp/decision.json --apply

See also

• Configuration — env vars.
• Output formats — table / json / markdown.
• Verb reference — per-verb schema details.