The `repoctl` command
repoctl is the operations program of this repository: a headless program in the layers of Kanon, run as bun run repoctl <verb> at the root, or as repoctl where installed from the package, and served as tools by repoctl mcp so that an AI agent runs the same deterministic operations as a person. Every fact it knows of the repository (the generators of its generated files, its checks, the commit identity and trailers, the hygiene policy) is in repoctl.config.ts at the root; a generator or a check is added there and nowhere else. See use repoctl in your own repository and add a verb.
A verb is a governance action with an effect (read, mutate or destructive), a tier that may see it (public, contributor, releaser; the host fixes it with REPOCTL_TIER, contributor where it says nothing) and a reach policy. The verbs share --json (one JSON document), --quiet and --verbose (and most --sarif and --color); those with a preview take --dry-run and those that check take --check. Findings come with a code that repoctl explain <code> explains, and repoctl help lists the verbs. The same descriptions are drawn in full in Programs.
Which verb for which job
- Make the generated files:
sync(sync --checkin CI and hooks). - Bring in
main:merge origin/main. - Say what is wrong:
check(the report),doctor(the checkout),explain <code>(a finding's meaning),hygiene(the consumption rule),status(versions). - Prove a change:
prove. - Commit:
commit -m "Subject" --refs N. - Release:
release plan,release apply,release publish(the release). - Add a library:
new library <name> --summary "...". - Documentation:
docs build,docs check,docs serve. - Ask in SQL:
query "SELECT ..."over the relationslibraries,specsandrequirements.
explain
repoctl explain <code> says what a finding's problem code means and what to do about it; it runs where there is no configuration. It is part of the program and not a verb of the table below, so it is written here: repoctl explain with no code lists the codes.
repoctl explain # the codes it can explain
repoctl explain <code> # what one finding means, and the command that fixes itThe commands
Read from the program's own typed verb definitions: each is declared once, and the command line, the tool server and these pages read that one table.
| Command | What it does | Effect | Tier | Preview | Check | Safe to repeat |
|---|---|---|---|---|---|---|
repoctl sync | Make every generated file, in dependency order, rerunning only the generators whose output is stale. | mutate | contributor | yes | yes | yes |
repoctl merge | Merge a reference, regenerate the generated files that conflict and report the conflicts in files a person wrote. | mutate | contributor | no | no | no |
repoctl check | Run every check of the repository (generated files, specifications, rules, versions) and say what is wrong in one report. | read | public | no | no | yes |
repoctl status | Tell, for each library, its version in the repository, on npm and in its tag. | read | public | no | no | yes |
repoctl hygiene | Say whether this repository consumes commons as published packages: no Git or path dependency, no vendored copy, one copy of each library, exact versions. | read | public | no | no | yes |
repoctl query | Ask the libraries, their specifications and their requirements in SQL: one read-only SELECT over the relations libraries, specs and requirements. | read | public | no | no | yes |
repoctl usage | Say what this repository uses of the package @intellectual-frontiers/commons: the libraries it imports, those reached through them and those never touched, with their sizes. | read | public | no | no | yes |
repoctl ci step | Run one step of a pipeline under the build policy: run the command given after --, keep what it prints, read it into findings with the parser of its tool, write the step's findings file and end 0 whatever the command's status was (commons 0038-build-policy FR-013). | mutate | contributor | no | no | no |
repoctl release plan | Say what a release would do, library by library and why; writes nothing. | read | public | no | no | yes |
repoctl release apply | Make a release: raise the versions the plan says, make the generated files, run the tests that pack and write the record; commits nothing. | mutate | contributor | yes | no | no |
repoctl release publish | Publish the packed libraries of the release record to npm, behind the releaser tier and a typed confirmation. | destructive | releaser | yes | no | no |
repoctl new library | Scaffold a library of commons: its folder, manifest, about.ts, specification kit, tools, tsconfig and LICENSE, and make what needs it again. | mutate | contributor | yes | no | no |
repoctl commit | Make the commit with the repository's identity and trailers, refusing what must not be committed, after the generated files are checked. | mutate | contributor | yes | no | no |
repoctl doctor | Say what is wrong with this checkout (dependencies, links, Node, Bun, stale generated files) and what to do about it. | read | public | no | no | yes |
repoctl prove | Compute the proof a change needs from its blast radius (the tiers, the tests and why each skipped proof is safe) and run it. | read | public | no | no | yes |
repoctl docs build | Build the documentation site of this repository with the documentation generator, into the folder its configuration names. | mutate | contributor | yes | no | yes |
repoctl docs serve | Build the documentation site and serve it on a loopback port of this computer until the run is stopped; nothing is uploaded. | mutate | contributor | yes | no | yes |
repoctl docs check | Build the documentation site into a temporary folder and say every finding, writing nothing in the repository. | read | public | no | no | yes |
repoctl mcp | Serve the verbs the held tier sees as tools of a tool server on standard input and output. | read | public | no | no | yes |
repoctl sync
Make every generated file, in dependency order, rerunning only the generators whose output is stale.
| Option | Meaning |
|---|---|
--only | Only these generators, as ids separated by commas (those of the configuration). |
--dry-run | Show what would change and change nothing. |
--check | Change nothing; end with findings where something would change. |
repoctl sync # Make every generated file that is stale, in dependency order.
repoctl sync --check # Write nothing; exit 1 naming each stale generator and the command that fixes it (what CI and the hooks run).
repoctl sync --dry-run # Say which generators would be run.
repoctl sync --only readme,license # Only the generators of the README and the licenses.The full page of this verb: repoctl sync.
repoctl merge
Merge a reference, regenerate the generated files that conflict and report the conflicts in files a person wrote.
repoctl merge origin/main # Merge main; a generated file that conflicts is made again, never resolved by hand.
repoctl merge some-branch # Merge a branch; a conflict in a file a person wrote is reported and left as Git left it.The full page of this verb: repoctl merge.
repoctl check
Run every check of the repository (generated files, specifications, rules, versions) and say what is wrong in one report.
repoctl check # Run every check: the generated files, the specification kits, the rules of Mizan, the versions and the constants that say a version.
repoctl check --json # The same, as one JSON document: each section with its findings, their codes and their fixes.The full page of this verb: repoctl check.
repoctl status
Tell, for each library, its version in the repository, on npm and in its tag.
| Option | Meaning |
|---|---|
--offline | Ask no network: npm is not asked, and the tags are those of the local clone. |
repoctl status # The version of each library in the repository, on npm and in its tag.
repoctl status --offline # The same without the network: npm is not asked and the tags are the local ones.
repoctl status --json # The rows as one JSON document.The full page of this verb: repoctl status.
repoctl hygiene
Say whether this repository consumes commons as published packages: no Git or path dependency, no vendored copy, one copy of each library, exact versions.
repoctl hygiene # Say whether this repository consumes the family's packages only as published packages: findings with their code and path, and the exit status 1 where one fails.
repoctl hygiene --json # The same as one JSON document: the repository, the findings with their code, level, path, message and fix, and the counts.The full page of this verb: repoctl hygiene.
repoctl query
Ask the libraries, their specifications and their requirements in SQL: one read-only SELECT over the relations libraries, specs and requirements.
| Option | Meaning |
|---|---|
--limit | The most rows of the answer. |
repoctl query SELECT library, count(*) AS n FROM requirements WHERE mechanism = 'none' GROUP BY library # Count the requirements that nothing verifies, library by library.
repoctl query SELECT name, version FROM libraries ORDER BY name --json # The libraries with their versions, as one JSON document.The full page of this verb: repoctl query.
repoctl usage
Say what this repository uses of the package @intellectual-frontiers/commons: the libraries it imports, those reached through them and those never touched, with their sizes.
| Option | Meaning |
|---|---|
--root | The repository to read (the repository repoctl runs in by default). |
--package | The folder of the installed package (node_modules/@intellectual-frontiers/commons of the repository by default). |
repoctl usage # What this repository uses of the package: the libraries imported, those reached through them and those never touched.
repoctl usage --root ../erga --package ../erga/node_modules/@intellectual-frontiers/commons --json # The same for another repository, as one JSON document.The full page of this verb: repoctl usage.
repoctl ci step
Run one step of a pipeline under the build policy: run the command given after --, keep what it prints, read it into findings with the parser of its tool, write the step's findings file and end 0 whatever the command's status was (commons 0038-build-policy FR-013).
| Option | Meaning |
|---|---|
--id | The step's id: letters, digits, dots, hyphens and underscores. |
--job | The job the step is in. |
--module | The module (library) its findings are of. |
--tool | The tool whose output is read: tsc, bun-test, lint, format, repoctl-check, mizan-check, kanon-check, generated-files, verify, checks, exit-status, install. |
--timeout | The minutes after which the command is stopped. |
--out | The folder the step's findings file is written to. |
repoctl ci step --id tests --tool bun-test -- bun test # Run the tests and keep the failing ones as findings.The full page of this verb: repoctl ci step.
repoctl release plan
Say what a release would do, library by library and why; writes nothing.
| Option | Meaning |
|---|---|
--offline | Do not ask npm what it holds: a version with no tag is then raised only where its files changed since it was raised. |
--distribution | The distribution mode for this run: per-library or single (the mode of the repository, or IFC_DISTRIBUTION, where it is not given). |
--raise | Raise a library whatever its state says: NAME, or NAME=major|minor|patch. |
repoctl release plan # What a release would do, library by library and why; nothing is written.
repoctl release plan --offline # The same without asking npm.
repoctl release plan --raise headless=minor # Plan the release with headless raised by a minor.The full page of this verb: repoctl release plan.
repoctl release apply
Make a release: raise the versions the plan says, make the generated files, run the tests that pack and write the record; commits nothing.
| Option | Meaning |
|---|---|
--offline | Do not ask npm what it holds: a version with no tag is then raised only where its files changed since it was raised. |
--distribution | The distribution mode for this run: per-library or single (the mode of the repository, or IFC_DISTRIBUTION, where it is not given). |
--raise | Raise a library whatever its state says: NAME, or NAME=major|minor|patch. |
--tests | Run the tests that pack, install and type-check every library (on by default). |
--dry-run | Show what would change and change nothing. |
repoctl release apply --dry-run # The plan, with nothing written.
repoctl release apply # Raise the versions the plan says, make every generated file, run the tests that pack and write the record.
repoctl release apply --no-tests # The same without the tests that pack: for trying the command, never for a release.The full page of this verb: repoctl release apply.
repoctl release publish
Publish the packed libraries of the release record to npm, behind the releaser tier and a typed confirmation.
| Option | Meaning |
|---|---|
--confirm | The confirmation the preview printed (`publish <n> <digest>`), typed by the person who publishes. |
--dry-run | Show what would change and change nothing. |
--yes | Confirm the destruction without asking. |
repoctl release publish --dry-run # The releases that would be sent, and the confirmation to type.
repoctl release publish --yes --confirm 'publish 3 1a2b3c4d' # Send them to npm, with the confirmation the preview printed (the releaser tier, INFRO_NPMJS_TOKEN in the environment).The full page of this verb: repoctl release publish.
repoctl new library
Scaffold a library of commons: its folder, manifest, about.ts, specification kit, tools, tsconfig and LICENSE, and make what needs it again.
| Option | Meaning |
|---|---|
--summary | What the library is, in a sentence or two: its first sentence is its row in the README. |
--role | Where the README puts it: foundation, pattern, program or standard. |
--dry-run | Show what would change and change nothing. |
repoctl new library widget --summary Widgets, made by the book. # Scaffold the library widget in the libraries' folder with its manifest, spec kit, tools and LICENSE.
repoctl new library widget --summary Widgets. --dry-run # List the files that would be made, and write nothing.The full page of this verb: repoctl new library.
repoctl commit
Make the commit with the repository's identity and trailers, refusing what must not be committed, after the generated files are checked.
| Option | Meaning |
|---|---|
--message | The subject of the commit: one line of at most 100 characters, with no full stop at its end. |
--refs | The issue the commit refers to: its number, written as the line `Refs #N`. |
--impact | How much the release raises the version of a library this commit changes: major (a breaking change; a minor while the major version is 0), minor (a feature) or patch (a fix), written as the line `Impact:`. |
--session | The address of the session, written as the line `Claude-Session` (else the variable CLAUDE_SESSION_URL). |
--co-author | The line that credits the agent (else the variable REPOCTL_CO_AUTHOR, else the configuration's). |
--dry-run | Show what would change and change nothing. |
repoctl commit -m Add the doctor --refs 10 # Commit what is staged, as the repository's identity, with the trailers its configuration lists (`Refs #10`, the co-author, the session).
repoctl commit -m Fix the merge --dry-run commons/repoctl/src # Show the message and the files, and commit nothing.The full page of this verb: repoctl commit.
repoctl doctor
Say what is wrong with this checkout (dependencies, links, Node, Bun, stale generated files) and what to do about it.
repoctl doctor # What is wrong with this checkout, in the order to fix it, and the command for each.The full page of this verb: repoctl doctor.
repoctl prove
Compute the proof a change needs from its blast radius (the tiers, the tests and why each skipped proof is safe) and run it.
| Option | Meaning |
|---|---|
--base | The revision the change starts at (origin/main, else main, else HEAD). |
--plan | Print the plan as one JSON document and run nothing. |
--why | Say, for every proof and every proof left out, why. |
--tier | Run only this tier (0 to 6 or T0 to T6). |
--all | Plan every proof of every tier, whatever changed. |
--no-cache | Run every selected test, whatever the cache holds. |
repoctl prove # Prove what the working tree changes since origin/main: the tiers T0 to T3 that apply, and only those.
repoctl prove --why # The same, with the sentence that says why each proof runs and why each skipped proof is safe to skip.
repoctl prove --plan # The plan as JSON, run nothing: what CI and the development loop read.
repoctl prove --tier 0 # Only the static proofs of the plan.
repoctl prove --all --plan # Every proof of every tier, as the nightly run and the release plan it.The full page of this verb: repoctl prove.
repoctl docs build
Build the documentation site of this repository with the documentation generator, into the folder its configuration names.
| Option | Meaning |
|---|---|
--out | The folder to build into (the configuration's docs.out by default). |
--dry-run | Show what would change and change nothing. |
repoctl docs build # Build the site into the folder the configuration names.
repoctl docs build --dry-run # Say what the generator would be asked, and build nothing.The full page of this verb: repoctl docs build.
repoctl docs serve
Build the documentation site and serve it on a loopback port of this computer until the run is stopped; nothing is uploaded.
| Option | Meaning |
|---|---|
--port | The loopback port to serve on (0 lets the system choose). |
--for | Stop after this many seconds (else it serves until it is interrupted). |
--dry-run | Show what would change and change nothing. |
repoctl docs serve # Build the site and serve it on http://127.0.0.1:4173/ until Ctrl-C.
repoctl docs serve --port 0 --for 30 # Serve on a port the system chooses, and stop after 30 seconds.The full page of this verb: repoctl docs serve.
repoctl docs check
Build the documentation site into a temporary folder and say every finding, writing nothing in the repository.
repoctl docs check # Build the site into a temporary folder and say every finding; nothing is written in the repository.The full page of this verb: repoctl docs check.
repoctl mcp
Serve the verbs the held tier sees as tools of a tool server on standard input and output.
repoctl mcp # Serve the tools of the tier the host holds (REPOCTL_TIER; REPOCTL_READ_ONLY=1 serves only what reads).The full page of this verb: repoctl mcp.