CLI

regulator is the bin of @metacoding.io/regulator. Every command runs against the instance in the current working directory (the base checkout regulator init was run in) and the definition that ships with the package; --policy, --recovery, --routing and --interaction point a command at a different policy file for one run.

pnpm add -D @metacoding.io/regulator @metacoding.io/regulator-pi
pnpm regulator doctor

Instance

init [<dir>] [--writable a/,b/] [--protected x/] [--by <who>]

regulator init [<dir>] [--writable a/,b/] [--protected x/] [--by <who>]

Install the definition into an existing repository: identity seeded and committed, .regulator/ ignored, canaries recorded, the instance manifest written

doctor [--json] [--today <date>]

regulator doctor [--json] [--today <date>]

The operating check: runtime, git, the Pi pin, the definition, review dates, the instance; exit 1 on a problem

status [--definition <dir>] [--instance <dir>] [--json]

regulator status [--definition <dir>] [--instance <dir>] [--json]

A read-only projection of the definition and the instance (what the control room renders)

check [--today <date>]

regulator check [--today <date>]

Validate the registry and the rest of the definition; exit 1 on a problem or an overdue review date

docs [--write | --check]

regulator docs [--write | --check]

Render REGULATORS.md and BOUNDARY.md from the registry records

watch [--once] [--interval <ms>] [--exec <cmd> [args…]]

regulator watch [--once] [--interval <ms>] [--exec <cmd> [args…]]

The outbox watcher: deliver, remind, forward each new line to a channel command

fixture <dest> [--oscillation | --injection | --finance]

regulator fixture <dest> [--oscillation | --injection | --finance]

Copy a fixture into its own git repo (identity seeded, canaries recorded)

Units

unit drive <contract.json> [--policy <file>] [--recovery <file>] [--routing <file>]

regulator unit drive <contract.json> [--policy <file>] [--recovery <file>] [--routing <file>]

The autoloop: run, route, and run again while the policy says so

unit dispatch <contract.json> [--policy <file>] [--routing <file>] [--host <package>] [--quiet]

regulator unit dispatch <contract.json> [--policy <file>] [--routing <file>] [--host <package>] [--quiet]

Run one unit through the S3 loop with a live host session

unit start <id> [--type <unitType>] [--workload <name>] [--ttl <min>] [--host <package>]

regulator unit start <id> [--type <unitType>] [--workload <name>] [--ttl <min>] [--host <package>]

Lease + worktree + branch by hand (run in the base checkout); prints the host's session command

unit finish <id>

regulator unit finish <id>

Reintegrate a unit started by hand, or surface the conflict

unit status

regulator unit status

Leases and their liveness

unit show <id>

regulator unit show <id>

The unit record, attempts, decisions, report and obligations

unit route <id>

regulator unit route <id>

Route one blocked unit under the recovery policy and print the decision

unit close <id>

regulator unit close <id>

Re-audit a blocked unit without an attempt and close it if the verdict is pass

unit accept <id> <criterion> --by <who> [--reject] [--note <text>]

regulator unit accept <id> <criterion> --by <who> [--reject] [--note <text>]

A human disposition of a criterion no check can observe

unit evidence <id>

regulator unit evidence <id>

Replay the unit's audit log: evidence, verdicts, acceptances

contract check <file>

regulator contract check <file>

Validate a work contract against the schema and the workload

Obligations

obligations [--all]

regulator obligations [--all]

What is owed and to whom; --all includes closed ones

obligation show <id>

regulator obligation show <id>

One obligation with its history (id or unique prefix)

obligation ack <id> --by <who> [--note <text>]

regulator obligation ack <id> --by <who> [--note <text>]

Acknowledge without resolving

obligation resolve <id> --by <who> --disposition <d> --rationale <text>

regulator obligation resolve <id> --by <who> --disposition <d> --rationale <text>

Close it: no-action, accepted-risk, rework, replan, fixed, verified, rejected, research-requested, audit-requested, policy-clarification-requested

obligation escalate <id> --by <who> --to <consumer> --rationale <text>

regulator obligation escalate <id> --by <who> --to <consumer> --rationale <text>

Hand it to another consumer; the successor inherits the veto

answer <obligation> --by <who> --answer <text>

regulator answer <obligation> --by <who> --answer <text>

Answer a question a unit asked: recorded as the person's disposition; the next attempt carries it

remind

regulator remind

Deliver again every obligation owed to a person that has waited longer than the policy's reminder interval

signals route

regulator signals route

Route every unrouted message under the routing policy (for sessions run by hand)

Identity and memory

identity accept <obligation> --by <who> --file <IDENTITY|INVARIANTS|GLOSSARY|BOUNDARIES>.md --from <path> --rationale <text>

regulator identity accept <obligation> --by <who> --file <IDENTITY|INVARIANTS|GLOSSARY|BOUNDARIES>.md --from <path> --rationale <text>

The S5 decision: write the proposed file into regulator/identity/ under S5 authority, commit it on the base branch citing the obligation, and resolve the obligation as accepted

identity reject <obligation> --by <who> --rationale <text>

regulator identity reject <obligation> --by <who> --rationale <text>

Decline a proposal owed to S5

identity promote <IDENTITY|INVARIANTS|GLOSSARY|BOUNDARIES>.md --by <who> --rationale <text> [--definition <dir>]

regulator identity promote <IDENTITY|INVARIANTS|GLOSSARY|BOUNDARIES>.md --by <who> --rationale <text> [--definition <dir>]

The release path: copy the instance's accepted identity file into the definition's seed (the manifest's, or --definition) and commit it there

memory [--all]

regulator memory [--all]

Operational memory: current facts; --all includes expired and retracted

memory retract <id> --by <who> --reason <text>

regulator memory retract <id> --by <who> --reason <text>

Retract a fact; the retraction is appended, nothing is deleted

Evidence

effects

regulator effects

The effect journal: every side-effecting tool call, its outcome and its reconciliation

spans [--json]

regulator spans [--json]

The instance's records as OpenTelemetry GenAI spans, redacted (NDJSON with --json)

eval <suite.json> [--behaviour <reference|drifter|sloppy|self-certifier>] [--arm <name>]... [--reps <n>] [--out <file>] [--interpretation <file>] [--by <who>] [--keep] [--host <package>]

regulator eval <suite.json> [--behaviour <reference|drifter|sloppy|self-certifier>] [--arm <name>]... [--reps <n>] [--out <file>] [--interpretation <file>] [--by <who>] [--keep] [--host <package>]

Run a suite: scripted units headlessly, or live units through the host's dispatcher

review [--due] [--within <days>]

regulator review [--due] [--within <days>]

The registry's review dates; --due lists what is overdue or due within the window

Authority

Every --by that dispositions something is checked against the interaction policy's people: a name not listed may disposition nothing, and what a listed person may do (severity, accepted-risk, S5) is declared there; unit accept is checked at blocking. init and eval record --by as provenance without the check. The name itself is asserted, not authenticated. regulator check and regulator docs (the definition check and the generated registry documents) are implemented in registry-cli.ts and reached through this entry point.

The definition's own commands

The definition check and the generated registry documents are a second entry point, registry-cli.js in the same package, run from the workspace:

pnpm --filter @metacoding.io/regulator registry:check   # validate the registry and the definition; exit 1 on a problem
pnpm --filter @metacoding.io/regulator registry:docs    # rewrite registry/REGULATORS.md and BOUNDARY.md

registry:check runs under pnpm check, so a record whose review date has passed fails the build.