prworlds — CLI

The CLI is how a repo asks to be inhabited.

npx prworlds init

One command. It detects your project, your database, and your agent — then connects PR Worlds so your agent can invoke worlds on its own. Or use the CLI directly:

npx prworlds open --db postgresql://localhost:5432/mydb

Five seconds later: a coherent, reproducible world — relational state with real integrity — exists in your database under a schema you can point your app at.

What this is

PR Worlds is a piece of the habitar layer — the layer where humans and agents build with real state instead of in a vacuum. Each world is a coherent, reproducible state of your system: schema + data + relationships + integrity, identified by a fingerprint.

The CLI is one of the three surfaces through which worlds are invoked. The others are the GitHub Action (for PRs) and the MCP server (for agents with capability discovery). All three are doors to the same room.

For agents (Claude Code, Cursor, Copilot, Cowork, local LLMs)

When the user is building a feature that depends on realistic data, and the database is empty or the state is incoherent, invoke:

prworlds open --db "$DATABASE_URL" --json

The JSON output:

{
  "world": { "fingerprint": "a3c17e9bd82f0145", "scenario": "default", "instance": "prworlds_local_1" },
  "stats": { "rows": 150, "tables": 8, "integrityValid": true },
  "ledger": { "path": "./.prworlds/ledgers/a3c17e9bd82f0145.json" },
  "next": [
    { "label": "inspect", "command": "prworlds inspect a3c17e9bd82f0145" },
    { "label": "replay", "command": "prworlds replay a3c17e9bd82f0145" }
  ]
}

Pass world.instance (the schema name) to subsequent DB operations. The world is deterministic — the same fingerprint in the same project materializes the same state byte-for-byte.

When the user has not said what kind of world:

prworlds suggest --db "$DATABASE_URL" --json

Returns ranked suggestions coherent with the current repo — use the top id as --scenario for open.

When the user wants to pass their intent:

prworlds open --scenario "invoice_reconciliation_peak" --intent "concentrate invoices near reconciliation deadline with edge-case states"

The CLI accepts free-form scenarios. Unknown names are resolved from intent (heuristically) or from an explicit plan (--plan <file> for full control).

Commands

prworlds init

Prepare a repo to be inhabited. The first gesture. One command that:

• Detects your project (name, package.json, README) and your database (env, .env files, or asks once).
• Tests the connection so you know it works before anything else runs.
• Detects MCP-aware agents on your machine — Cursor, Claude Code, Claude Desktop, Windsurf, Cline — and offers to inject the PR Worlds MCP config into their settings (preserving any other servers already configured).
• Runs suggest so you immediately see what worlds fit this repo.
• Closes with a single invitation: "Your repo is ready to be inhabited."

npx prworlds init                              # auto-detect everything
npx prworlds init --yes                        # skip prompts (for CI)
npx prworlds init --db postgres://… --agent cursor
npx prworlds init --agent none                 # CLI-only, no agent config

After init, your agent can discover PR Worlds and invoke the seven world tools through MCP on its own. The CLI verbs below still work directly — init doesn't replace them, it prepares the door.

prworlds open

Open a world into your database. The canonical verb.

prworlds open [options]

Flags:

| Flag | Meaning | |---|---| | --db <url> | PostgreSQL connection (falls back to DATABASE_URL) | | --scenario <name> | Scenario that biases the world. Free-form — see Scenarios below | | --salt <value> | Salt for the fingerprint (default: the project name) | | --intent <text> | Free-form intent; used to resolve unknown scenarios | | --plan <file> | Plan JSON. Accepts both a ResolvedPlan (from prworlds resolve --json) and a raw GenerationPlan | | --plan-stdin | Read plan from stdin (for agents piping resolve --json directly into open) | | --planner <mode> | heuristic (default, free, fast) | llm (requires OPENAI_API_KEY) | auto | | --json | Output structured JSON | | --quiet | Print only the fingerprint |

When --plan carries a ResolvedPlan, open uses the plan's canonical form to compute the fingerprint (v1.1) and writes a ledger v2 with the plan attached. This makes future replay byte-stable across planner versions.

prworlds resolve

Convert an intention into a form a world can take, without touching the database. Produces a resolved plan you can inspect, share, pipe into open, or discard.

prworlds resolve [options]

Flags: same as open, except resolve does not write to the DB. Common patterns:

# See what would happen if you opened a world for this scenario
prworlds resolve --scenario trial_expiring

# Capture the canonical plan for stable replay later
prworlds resolve --scenario trial_expiring --json > plan.json
prworlds open --plan plan.json

# Pipe directly — same effect
prworlds resolve --scenario trial_expiring --json | prworlds open --plan-stdin

The resolved plan has four blocks:

• identity — what world this would be (schemaHash, scenario, salt, engineVersion, planSchemaVersion)
• shape — what form it takes (the full generationPlan + artifactSlots)
• diagnostics — how the system arrived (negotiations, warnings, predictedIntegrity, plan source)
• narrative — what to communicate to the user (what would be emphasized, where to look first, what would NOT be emphasized)

The fingerprint depends only on identity + shape — narrative and diagnostics do not affect identity.

See docs/LANGUAGE.md § The resolved plan for the ontological framing.

prworlds replay <fingerprint>

Summon a known world by fingerprint into a new instance. Resolves from the local ledger (.prworlds/ledgers/).

When the ledger is v2 (carries the resolved plan), replay materializes from the plan's canonical shape directly — byte-for-byte identical recurrence, even across planner versions. When the ledger is v1 (legacy), replay re-derives via the planner; determinism is preserved as long as the planner has not changed.

prworlds suggest

Propose scenarios coherent with this repo. Heuristic, zero cost, no LLM call.

prworlds inspect [<fingerprint>]

Observe a world without entering it. Without a fingerprint, shows the most recent.

prworlds list

Show worlds with local ledgers in this project.

prworlds destroy <fingerprint>

Drop the instance schema. The ledger is preserved — the world remains replayable.

prworlds mcp serve

Run the MCP (Model Context Protocol) server over stdio. Agents that speak MCP — Claude Code, Cursor, Cowork, and others — can launch this as a subprocess to discover and invoke PR Worlds capabilities natively, without parsing CLI output.

See MCP integration below.

MCP integration

The MCP surface exposes the verbs as discoverable tools that agents call directly. No shell-out, no stdout parsing — agents see structured tool definitions and invoke them with typed arguments.

Configuration (Claude Code, Cursor, etc.):

{
  "mcpServers": {
    "pr-worlds": {
      "command": "npx",
      "args": ["prworlds", "mcp", "serve"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}

Tools the agent gets:

| Tool | When the agent invokes it | |---|---| | suggest_worlds | The user has not chosen a scenario; the agent wants ranked options coherent with the repo | | resolve_world | The agent wants to preview what a world would become before opening it — see negotiations, warnings, predicted integrity, narrative | | open_world | The user is building a feature that needs realistic data, or the database is empty | | replay_world | The user wants the exact same state as a previous world (by fingerprint) | | inspect_world | The agent or user wants to understand an existing world without entering it | | list_worlds | See what worlds are available locally | | destroy_world | Drop an instance schema; ledger stays so the world remains replayable |

The natural cycle is see → decide → materialize: suggest_worlds reads the repo (no DB writes), resolve_world converts intent into a plan (no DB writes), open_world materializes the plan into a world. The agent can compress these into a single open_world call when intent is clear, or let the user inspect the resolved plan before committing.

Resources the agent can read:

• prworlds://repo/context — what PR Worlds sees about this repo, plus suggestions
• prworlds://ledgers — all local ledgers, ordered by recency
• prworlds://ledgers/{fingerprint} — a specific ledger by fingerprint

Outputs include a narrative field (what was emphasized, where to look first, what was deliberately untouched) so the agent can communicate with the user without inventing meaning the system already knows. Errors include suggested_actions so the agent can recover by invoking the right tool with the right arguments.

Scenarios

A scenario is a free-form string that names the intentional bias of a world. It does not need to exist in a catalog to be valid — it needs to be resolvable.

Resolution happens in resolve (and implicitly in open when no plan is provided). Four modes:

• Default — default (or none, or empty) is always resolvable. It is the absence of bias: the world materializes in its baseline coherent state. Default is not a catalog entry; it is the ground state.
• Known — matches a curated scenario with built-in mappings (trial_expiring, payment_failed, suspended_account, ...). Zero friction.
• Plan-provided — free-form name, but you pass --plan <file> (a ResolvedPlan from prworlds resolve, or a raw GenerationPlan). Maximum control.
• Intent-resolvable — free-form name plus --intent "...". The planner interprets the intent against the schema, and the interpretation is surfaced — never hidden.

If none of those apply, the CLI fails clearly rather than producing an empty world labeled with the name.

Run prworlds suggest to see known scenarios appropriate for your repo, or prworlds resolve --scenario "<your name>" --intent "<description>" to translate a free-form intent into a plan.

Project context

The CLI reads the following before it asks:

• prworlds.json > project.name (if present)
• package.json > name and description (if present)
• README.md (first ~2000 chars, used as planner context)
• Falls back to the directory name

This context is passed to the planner (for heuristic scenario suggestions) and feeds the default salt (so two distinct projects with identical schemas produce different worlds).

The local ledger

Every open and replay writes a ledger at ./.prworlds/ledgers/<fingerprint>.json. This ledger is what makes worlds replayable across time — even if the instance schema is dropped, the world remains summonable.

You can .gitignore the folder (ledgers private to the developer) or commit it (team shares the same replayable worlds). That decision belongs to the repo.

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | User error (no DB, invalid fingerprint, unresolvable scenario) | | 2 | Integrity violations detected post-seed (world opened, but invalid) | | 3 | Unexpected error |

Where to learn more

• LANGUAGE.md — canonical vocabulary: world, fingerprint, scenario, replay, pin, inspect, ...
• The Action — the other door to the same worlds, for GitHub PRs