Install

The PETROVA CLI is a Node.js + TypeScript package living at petrova-hq/cli/. It builds to a self-contained dist/ and links as a global binary.

Prerequisites

• Node.js ≥ 20.
• npm (or pnpm — package-lock.json is npm’s; pnpm reads it but generates its own warnings).
• git for cloning.

Install

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

Verify:

petrova verbs

Should print all nine verb names (close_phase, diagnose, …, verify_round).

What npm link does

npm link creates a symlink from npm config get prefix’s bin/ directory to petrova-hq/cli/dist/index.js. After this, petrova is available globally for the current user. To remove:

npm unlink -g @petrova/cli

If npm link requires sudo on your system (it does on macOS with the system Node), follow npm’s prefix configuration guide to use a user-owned prefix.

Workspace assumption

By default, PETROVA reads governed repos from $PETROVA_WORKSPACE/<slug>. If PETROVA_WORKSPACE is unset, the default is the parent directory of petrova-hq. So:

~/code/workspace/
├── petrova-hq/      # control plane (this repo)
├── kahn-hq/         # consumer repo (slug: kahn-hq)
└── smo1-io/         # consumer repo (slug: smo1-io)

Override the workspace:

export PETROVA_WORKSPACE=/path/to/your/workspace

The petrova-hq self-entry always resolves to the petrova-hq directory itself, regardless of PETROVA_WORKSPACE.

Dev mode (no link)

If you don’t want to link globally:

cd petrova-hq/cli
npm run dev -- status
npm run dev -- diagnose petrova-hq

npm run dev runs the TypeScript directly via tsx without a build step — useful when iterating on the CLI itself.

Updating

cd petrova-hq
git pull
git submodule update --recursive
cd cli
npm install
npm run build

The link from npm link survives across builds — it points at dist/index.js which gets rewritten by npm run build.

See also

• Auth — credentials for --apply.
• Configuration — environment variables.
• Quickstart — end-to-end first use.