Skip to content
PETROVA

Quickstart

End-to-end from zero to a successful dry-run, in ≤5 minutes. This walks the read path; auth is needed only for --apply (last step).

1. Clone + install

Section titled “1. Clone + install”
Terminal window
cd ~/code/workspace
git clone https://github.com/petrova-hq/petrova.git petrova-hq
cd petrova-hq
git submodule update --init --recursive


cd cli
npm install
npm run build
npm link             # makes `petrova` available globally

Verify the binary:

Terminal window
petrova verbs        # lists all 9 verb names

2. (Optional) clone a governed repo

Section titled “2. (Optional) clone a governed repo”

PETROVA reads from local clones for diagnose / status / validate. Clone any repo listed in registry.yaml:

Terminal window
cd ~/code/workspace
git clone https://github.com/kahn-hq/kahn.git kahn-hq

By default, PETROVA looks for repos at $PETROVA_WORKSPACE/<slug> where PETROVA_WORKSPACE defaults to the parent of petrova-hq. The petrova-hq self-entry resolves to its own root.

3. First read verb

Section titled “3. First read verb”
Terminal window
petrova status

Output:

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

Try a single-repo deep dive:

Terminal window
petrova diagnose petrova-hq --since 2026-04-01

Or compliance check:

Terminal window
petrova validate petrova-hq
# → MR-7, MR-4, MR-12 all pass.

No GitHub auth was needed for any of this.

4. First dry-run write

Section titled “4. First dry-run write”

Compose a verb input. open_decision is the simplest write verb:

Terminal window
cat > /tmp/decision.json <<'JSON'
{
  "title": "Smoke test",
  "slug": "smoke-test-quickstart",
  "context": "Verifying I can dry-run a write verb end-to-end.",
  "decision": "If this preview looks right, my install is good.",
  "alternatives_considered": [
    {"name": "skip the test", "rejection_reason": "would skip a real verification"},
    {"name": "go straight to --apply", "rejection_reason": "always dry-run first"}
  ]
}
JSON


petrova open_decision petrova-hq --input /tmp/decision.json

Output:

open_decision → dry_run  4f8c3e21d97a
  upholds: MR-4, MR-7
  branch: petrova/open-decision/smoke-test-quickstart
  create docs/decisions/2026-04-29-smoke-test-quickstart.md (454 B)

No PR exists yet. The diff preview shows what --apply would emit. You can do this all day without a token; auth is only required for the next step.

5. (Optional) apply

Section titled “5. (Optional) apply”

To actually emit a PR, set PETROVA_GITHUB_TOKEN (a fine-grained PAT with Contents + Pull Requests scopes for the target repo) and re-run with --apply:

Terminal window
export PETROVA_GITHUB_TOKEN="<token>"
petrova open_decision petrova-hq --input /tmp/decision.json --apply
# → applied  4f8c3e21d97a
#   PR #N petrova/open-decision/smoke-test-quickstart https://github.com/.../pull/N

Re-running with the same input is a no-op:

Terminal window
petrova open_decision petrova-hq --input /tmp/decision.json --apply
# → skipped_idempotent  4f8c3e21d97a
#   PR #N (same as before)

Close the smoke-test PR without merging when you’re done — the decision was synthetic.

Where to go next

Section titled “Where to go next”