Output formats

PETROVA CLI commands support up to three output formats. The default varies by command; the format is chosen via flags.

The three formats

Table (default for read commands)

Pretty-printed, terminal-friendly, with colour where supported. Designed for human quick-scan.

$ petrova status
slug         role            profile    local  phase  ms(open)  dec(30d)
petrova-hq   control-plane   strict     ✓      —      0         1
kahn-hq      production      standard   ✓      —      75        24

`--json`

Raw JSON conforming to the verb’s output schema. Designed for agent-fleet consumption, scripting, jq pipelines.

$ petrova status --json | jq '.rows[].slug'
"petrova-hq"
"kahn-hq"

`--format markdown` (dashboard only)

Markdown tables suitable for paste into GitHub Discussions, Notion, Slack. Includes totals, grouped sections, warnings.

$ petrova dashboard --format markdown
# Petrova fleet dashboard

*Scanned 2026-04-29T11:08:02Z*

**Totals:** 2 repo(s) · 2 local · 0 open phase(s) · 75 open milestone(s) · 25 decisions in last 30d.

## control-plane (1)
| slug | profile | local | phase | milestones (open) | decisions (30d) |
|---|---|---|---|---|---|
| `petrova-hq` | strict | ✓ | — | 0 | 1 |
...

When to use which

Use case	Format
Daily check-in at the terminal	table
Script automation, CI parsing	`--json`
Agent fleet input/output	`--json`
Pasting into a notes app, GitHub Discussion	`--format markdown`
Programmatic re-rendering	`--json`
Verifying a verb’s schema-shape	`--json`

JSON shape stability

The --json output adheres to each verb’s output schema in spec/verbs/. Stability commitment:

Field additions are non-breaking. Schemas may grow.
Field removals are breaking. They require a schema fingerprint change (visible to consumers in the PR body) and a major version bump in the schema’s $id.
Field type changes are breaking. Same treatment.

Agent fleets relying on specific output shapes should pin against a schema fingerprint and re-validate when fingerprints change. See schema fingerprints.

What `--json` is NOT for

Pretty-printing. Use the default table for terminal viewing.
Markdown. Use --format markdown (only on dashboard).
Logging. Pipe --json to jq -c for one-line-per-event logging if needed.

Mixed flags

--json overrides format-specific flags. The following all produce JSON:

petrova dashboard --json
petrova dashboard --json --format markdown   # --json wins
petrova diagnose petrova-hq --json --scope decisions

Output formats

The three formats

Table (default for read commands)

--json

--format markdown (dashboard only)