rbit command reference

September 9, 2026 ยท View on GitHub

Generated from the argparse tree by python -m reprobit.cli_reference; tests/test_cli_reference.py fails when this file is stale. Commands appear in parser order. docs/cli.md explains the workflow around them.

Global options

ArgumentDefaultDescription
--versionshow the program version and exit
--format {text,ndjson}texthuman-readable text or stable machine events; accepted before or after the sub-command
--quietsilence text-mode progress (phase starts, heartbeats, unit counts); results, warnings and errors still print; ndjson output is unchanged; accepted before or after the sub-command

Every command also accepts -h/--help. The exit-status contract is in docs/cli.md.

Commands

rbit init

Start a ReproBit project.

rbit init [-h] [--project-id PROJECT_ID] [--profile {msvc_4_2,msvc_5_0_rtm,msvc_5_0_sp1,msvc_5_0_sp2,msvc_5_0_sp3}] [--target NAME] [--artifact [TARGET=]PATH] [--oracle [TARGET=]PATH] [--logical-source DOS_PATH] [--logical-build DOS_PATH] [--logical-toolchain DOS_PATH] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--project-id PROJECT_IDportable project name (default: derive it from the directory)
--profile {msvc_4_2,msvc_5_0_rtm,msvc_5_0_sp1,msvc_5_0_sp2,msvc_5_0_sp3}msvc_4_2compiler profile (default: msvc_4_2)
--target NAMEtarget name (repeatable; default: program)
--artifact [TARGET=]PATHrebuilt output path for one target, or TARGET=PATH when repeated (default: build/TARGET.exe)
--oracle [TARGET=]PATHoriginal/reference path for one target, or TARGET=PATH when repeated (default: reference/TARGET.exe)

advanced logical path options

Compiler-visible DOS paths recorded in reprobit.toml; every run maps its private source, output, and toolchain trees to exactly these spellings.

ArgumentDefaultDescription
--logical-source DOS_PATHR:\sourcecompiler-visible root of the source tree (default: R:\source)
--logical-build DOS_PATHR:\buildcompiler-visible root of the build output tree (default: R:\build)
--logical-toolchain DOS_PATHR:\toolchaincompiler-visible root of the compiler installation (default: R:\toolchain)

rbit setup

Prepare the compiler and this machine for a project.

rbit setup [-h] [--toolchain-root DIRECTORY] [--no-provision] [--no-save] [--skip-probe] [--backend {auto,posix_wine_v1,windows_native_v1}] [--wine PATH_OR_NAME] [--wineserver PATH_OR_NAME] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--toolchain-root DIRECTORYcompiler installation override (normally remembered by rbit setup)
--no-provisionfail instead of downloading a missing supported compiler
--no-savedo not remember this machine's compiler location
--skip-probeskip the bounded execution probe (faster, but less complete)

advanced host options

ArgumentDefaultDescription
--backend {auto,posix_wine_v1,windows_native_v1}autoexecution backend (default: select from the host platform)
--wine PATH_OR_NAMEwinePOSIX Wine executable (default: wine from PATH)
--wineserver PATH_OR_NAMEwineserverPOSIX wineserver executable (default: wineserver from PATH)

rbit doctor

Check this machine's backend and the selected compiler files.

rbit doctor [-h] [--backend {auto,posix_wine_v1,windows_native_v1}] [--wine PATH_OR_NAME] [--wineserver PATH_OR_NAME] [--execute-probe] [--profile {msvc_4_2,msvc_5_0_rtm,msvc_5_0_sp1,msvc_5_0_sp2,msvc_5_0_sp3}] [--toolchain-root DIRECTORY] [project]
ArgumentDefaultDescription
projectproject directory; omit it to check only this machine
ArgumentDefaultDescription
--backend {auto,posix_wine_v1,windows_native_v1}autoexecution backend (default: select from the host platform)
--wine PATH_OR_NAMEwinePOSIX Wine executable (default: wine from PATH)
--wineserver PATH_OR_NAMEwineserverPOSIX wineserver executable (default: wineserver from PATH)
--execute-probealso run the bounded backend and isolation probe (including Wine when used)
--profile {msvc_4_2,msvc_5_0_rtm,msvc_5_0_sp1,msvc_5_0_sp2,msvc_5_0_sp3}compiler profile when checking an installation without a project
--toolchain-root DIRECTORYcompiler installation to authenticate (default: use the project's remembered compiler when available)

rbit toolchain provision

Download and authenticate a supported compiler.

rbit toolchain provision [-h] [--destination DIRECTORY] [--no-save] [{msvc_4_2}]
ArgumentDefaultDescription
profile {msvc_4_2}msvc_4_2compiler profile (default: msvc_4_2)
ArgumentDefaultDescription
--destination DIRECTORYinstallation directory (default: this platform's standard user location)
--no-savedo not remember the installed compiler location

rbit toolchain lock

Record the exact compiler files this project expects.

rbit toolchain lock [-h] [--profile {msvc_4_2,msvc_5_0_rtm,msvc_5_0_sp1,msvc_5_0_sp2,msvc_5_0_sp3}] [--toolchain-root DIRECTORY] [--runtime-file RELATIVE_PATH] [--output PROJECT_RELATIVE_PATH] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--profile {msvc_4_2,msvc_5_0_rtm,msvc_5_0_sp1,msvc_5_0_sp2,msvc_5_0_sp3}compiler profile (default: read it from reprobit.toml)
--toolchain-root DIRECTORYcompiler installation override (normally remembered by rbit setup)
--runtime-file RELATIVE_PATHpin an additional wrapper or runtime dependency (repeatable)
--output PROJECT_RELATIVE_PATHlock-file path without reprobit.toml (existing projects always use their configured path)

rbit source preview

Show source changes and records that need review without writing.

rbit source preview [-h] [--path PATH] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--path PATHproject-relative file or tree to inspect (repeatable; defaults to the selection saved by the last lock, else Git tracked files)

rbit source export

Write the reviewed effective source view used by compilers and analysis tools.

rbit source export [-h] [--destination PROJECT_RELATIVE_DIRECTORY] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--destination PROJECT_RELATIVE_DIRECTORYbuild/reprobit-sourcedirectory to create or refresh (default: build/reprobit-source)

rbit source lock

Safely record tracked or explicitly named source inputs.

rbit source lock [-h] [--path PATH] [--invalidate-producer-graph] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--path PATHproject-relative file or tree to admit (repeatable, saved for later locks; defaults to the selection saved by the last lock, else Git tracked files)
--invalidate-producer-graphremove a stale generated graph in the same transaction after source changes

rbit source regenerate

Advanced maintenance tool. After editing an existing project file, normally run rbit repair . instead. This command only previews or applies the saved source-record updates; it does not build or verify the project.

rbit source regenerate [-h] [--apply] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--applysave the changes shown by the preview (default: preview without writing)

rbit import cmake

Prepare and record an ordinary CMake project in one guided run.

rbit import cmake [-h] [--target TARGET=CMAKE_TARGET] [--refresh] [--path PATH] [--keep-workspace {never,on-failure,always}] [--toolchain-root DIRECTORY] [--compiler-transport PATH] [--resource-transport PATH] [--cmake PATH_OR_NAME] [--configuration CONFIGURATION] [--cmake-define NAME=VALUE | --clear-cmake-defines] [--timeout SECONDS] [--directive-input TARGET=LIBRARY | --clear-directive-inputs] [--jobs COUNT] [--initialization-timeout SECONDS] [--compile-timeout SECONDS] [--link-timeout SECONDS] [--cleanup-timeout SECONDS] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--target TARGET=CMAKE_TARGETmap a ReproBit target during the first import (not used by --refresh)
--refreshupdate the saved source list and CMake build records as one verified change
--path PATHsource file or directory selected by --refresh (repeatable; default: Git index)
--keep-workspace {never,on-failure,always}on-failureretain temporary import files: never, on-failure (default), or always

advanced host and graph options

ArgumentDefaultDescription
--toolchain-root DIRECTORYcompiler installation override (normally remembered by rbit setup)
--compiler-transport PATHPOSIX transport selector for the locked compiler (paired with --resource-transport)
--resource-transport PATHPOSIX transport selector for the locked resource compiler
--cmake PATH_OR_NAMECMake executable (default: resolve cmake from PATH)
--configuration CONFIGURATIONsingle-configuration CMake build type (default: RelWithDebInfo)
--cmake-define NAME=VALUEset one CMake cache value (repeatable)
--clear-cmake-definesreplace saved CMake cache values with an empty list during --refresh
--timeout SECONDSbounded configure deadline (default: 600)
--directive-input TARGET=LIBRARYrecord one prelink-discovered default library edge (repeatable)
--clear-directive-inputsreplace saved default-library edges with an empty list during --refresh

refresh execution options

With --refresh, control the required build from scratch; --timeout controls CMake.

ArgumentDefaultDescription
--jobs COUNTmaximum parallel build workers (default: the CPUs this process may use, at most 8)
--initialization-timeout SECONDS600.0limit for each isolated execution-lane initialization (default: 600)
--compile-timeout SECONDS600.0limit for each compiler or resource-compiler step (default: 600)
--link-timeout SECONDS900.0limit for each librarian or linker producer (default: 900)
--cleanup-timeout SECONDS10.0limit for stopping each isolated execution lane and its wineserver (default: 10)

rbit graph configure

Create a fresh CMake metadata tree without building.

rbit graph configure [-h] --workspace-root EMPTY_DIRECTORY --toolchain-root DIRECTORY --compiler-transport PATH --resource-transport PATH [--cmake PATH_OR_NAME] [--configuration CONFIGURATION] [--cmake-define NAME=VALUE] [--timeout SECONDS] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--workspace-root EMPTY_DIRECTORYrequirednew or empty workspace that will receive fixed source/ and build/ trees
--toolchain-root DIRECTORYrequiredphysical root of the locally provisioned locked toolchain
--compiler-transport PATHrequiredadmitted compiler frontend used only for CMake feature detection
--resource-transport PATHrequiredadmitted resource-compiler frontend paired with the compiler transport
--cmake PATH_OR_NAMEcmakeCMake executable (default: resolve cmake from PATH)
--configuration CONFIGURATIONRelWithDebInfosingle-configuration CMake build type (default: RelWithDebInfo)
--cmake-define NAME=VALUEset one CMake cache value (repeatable)
--timeout SECONDS600.0bounded configure deadline (default: 600)

rbit graph extract

Record direct compiler and linker steps from that CMake tree.

rbit graph extract [-h] --configured-build-root DIRECTORY --effective-source-root DIRECTORY --effective-source-digest SHA256 --toolchain-root DIRECTORY [--target-plan TARGET_PLAN] [--configuration CONFIGURATION] [--cmake PATH_OR_NAME] [--timeout SECONDS] [--cmake-define NAME=VALUE] [--directive-input TARGET=LIBRARY] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--configured-build-root DIRECTORYrequiredCMake metadata tree created by rbit graph configure
--effective-source-root DIRECTORYrequiredeffective source tree whose physical paths match the configured commands
--effective-source-digest SHA256requiredsource receipt printed by the matching rbit graph configure run
--toolchain-root DIRECTORYrequiredphysical root matching the committed logical toolchain seat
--target-plan TARGET_PLANpath beneath the configured build (defaults to reprobit-target-plan.json)
--configuration CONFIGURATIONRelWithDebInfoconfiguration used by the matching graph configure run
--cmake PATH_OR_NAMEcmakeCMake executable used by the matching graph configure run
--timeout SECONDS600.0configure deadline used by the matching graph configure run
--cmake-define NAME=VALUECMake cache value used by the matching graph configure run (repeatable)
--directive-input TARGET=LIBRARYcommit one prelink-discovered DEFAULTLIB edge; repeat for each target/library

rbit validate

Check every saved project file.

rbit validate [-h] [project]
ArgumentDefaultDescription
project.project directory (default: .)

rbit cost

Show intervention cost totals.

rbit cost [-h] [project]
ArgumentDefaultDescription
project.project directory (default: .)

rbit status

Show what is ready and the next project setup step.

rbit status [-h] [--all] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--allinclude checks that already pass

rbit clean

Remove inactive workspaces; cache and reports are opt-in.

rbit clean [-h] [--preview] [--older-than-hours HOURS] [--cache | --obsolete-cache] [--reports] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--previewshow how much space can be freed without removing anything
--older-than-hours HOURSkeep workspace and cache entries newer than this age (default: 0)
--cachealso remove incremental and repair-search cache data selected by age
--obsolete-cachealso remove cache data this ReproBit version cannot reuse; keep the current cache
--reportsalso remove the canonical verification and grind reports

rbit explain

Explain saved interventions.

rbit explain [-h] [--intervention ID] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--intervention IDshow full details for one intervention

rbit repair

Use this after editing a file in a project that already matched exactly, including a shared header used by many source files. ReproBit repairs the saved build guidance in private, rebuilds, and publishes only after every target matches exactly. For added or removed files, start with source preview; it prints a safe next command when one is available.

rbit repair [-h] [--jobs COUNT] [--keep-workspace {never,on-failure,always}] [--backend {auto,posix_wine_v1,windows_native_v1}] [--wine PATH_OR_NAME] [--wineserver PATH_OR_NAME] [--toolchain-root DIRECTORY] [--compiler-transport PATH] [--resource-transport PATH] [--initialization-timeout SECONDS] [--compile-timeout SECONDS] [--link-timeout SECONDS] [--cleanup-timeout SECONDS] [--policy {clean,allow-quarantine}] [--report-dir PROJECT_RELATIVE_DIRECTORY] [--retune-radius DISTANCE] [--retune-candidates COUNT] [--candidate-limit COUNT] [--discovery-candidates COUNT] [--adjustment-rounds COUNT] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--jobs COUNTmaximum parallel build workers (default: the CPUs this process may use, at most 8)
--keep-workspace {never,on-failure,always}on-failurekeep the private workspace: never, only on failure, or always (default: on-failure)
--policy {clean,allow-quarantine}optionally narrow the project's committed authenticity policy
--report-dir PROJECT_RELATIVE_DIRECTORYwrite report.json and report.html beneath this project directory

Shared: see advanced execution options.

search bounds

Widen the bounded search for larger repairs; a completed repair must still reproduce every expected output in a build from scratch.

ArgumentDefaultDescription
--retune-radius DISTANCElargest declaration-count change tried per saved compiler choice or source layout (default: 8; max: 64)
--retune-candidates COUNTmaximum nearby settings tried per saved compiler choice or source layout (default: 64; max: 4096)
--candidate-limit COUNTmaximum nearby repair choices tested by the whole command (default: 256, or enough to hold an explicit --discovery-candidates budget; max: 65536)
--discovery-candidates COUNTfresh declaration settings built per affected source file after its saved compiler choices are exhausted (default: 64; max: 2133)
--adjustment-rounds COUNTmaximum saved-guidance adjustment rounds before repair stops (default: 24)

rbit build

Incrementally rebuild changed compiler and linker steps without CMake.

rbit build [-h] [--jobs COUNT] [--cold] [--keep-workspace {never,on-failure,always}] [--backend {auto,posix_wine_v1,windows_native_v1}] [--wine PATH_OR_NAME] [--wineserver PATH_OR_NAME] [--toolchain-root DIRECTORY] [--compiler-transport PATH] [--resource-transport PATH] [--initialization-timeout SECONDS] [--compile-timeout SECONDS] [--link-timeout SECONDS] [--cleanup-timeout SECONDS] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--jobs COUNTmaximum parallel build workers (default: the CPUs this process may use, at most 8)
--coldbuild from scratch without using the incremental cache
--keep-workspace {never,on-failure,always}on-failurekeep the private workspace: never, only on failure, or always (default: on-failure)

Shared: see advanced execution options.

rbit verify

Build every target from scratch and check exact bytes and trust evidence.

rbit verify [-h] [--jobs COUNT] [--keep-workspace {never,on-failure,always}] [--backend {auto,posix_wine_v1,windows_native_v1}] [--wine PATH_OR_NAME] [--wineserver PATH_OR_NAME] [--toolchain-root DIRECTORY] [--compiler-transport PATH] [--resource-transport PATH] [--initialization-timeout SECONDS] [--compile-timeout SECONDS] [--link-timeout SECONDS] [--cleanup-timeout SECONDS] [--policy {clean,allow-quarantine}] [--report-dir PROJECT_RELATIVE_DIRECTORY] [--action-receipt PATH] [--action-nonce LOWERCASE_SHA256] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--jobs COUNTmaximum parallel build workers (default: the CPUs this process may use, at most 8)
--keep-workspace {never,on-failure,always}on-failurekeep the private workspace: never, only on failure, or always (default: on-failure)
--policy {clean,allow-quarantine}optionally narrow the project's committed authenticity policy
--report-dir PROJECT_RELATIVE_DIRECTORYwrite report.json and report.html beneath this project directory
--action-receipt PATHpublish a nonce-bound completion receipt after both reports finalize
--action-nonce LOWERCASE_SHA25664-hex invocation nonce paired with --action-receipt

Shared: see advanced execution options.

rbit discover init

Create a small automatic search plan without compiling.

rbit discover init [-h] --source SOURCE --reference OBJECT_PATH --symbol SYMBOL [--translation-unit TRANSLATION_UNIT] [--plan PROJECT_RELATIVE_PATH] [project]
ArgumentDefaultDescription
project.project directory (default: .)
ArgumentDefaultDescription
--source SOURCErequiredproject-relative source file to explore
--reference OBJECT_PATHrequiredproject-relative .obj file containing the reference function
--symbol SYMBOLrequireddecorated function symbol
--translation-unit TRANSLATION_UNITselect one build of the source only when it is compiled more than once
--plan PROJECT_RELATIVE_PATHreprobit/discovery.jsonnew plan path (default: reprobit/discovery.json)

rbit discover run

Run a bounded request file (advanced).

rbit discover run [-h] [--report-json PATH] [--report-html PATH] [--state-directory DIRECTORY] [--jobs COUNT] [--wine PATH_OR_NAME] [--wineserver PATH_OR_NAME] [--toolchain-root DIRECTORY] [--compile-timeout SECONDS] [--cleanup-timeout SECONDS] request
ArgumentDefaultDescription
requestrequest JSON to run
ArgumentDefaultDescription
--report-json PATHcanonical JSON report beside the request (default: REQUEST_STEM.report.json)
--report-html PATHhuman review report beside the JSON report (default: REQUEST_STEM.report.html)
--state-directory DIRECTORY.reprobit-discoveryincremental cache and runtime state beside the request
--jobs COUNTmaximum compiler workers (Wine is safely capped at 4; default: the CPUs this process may use, at most 8)
--wine PATH_OR_NAMEwinePOSIX Wine executable (default: wine from PATH)
--wineserver PATH_OR_NAMEwineserverPOSIX wineserver executable (default: wineserver from PATH)
--toolchain-root DIRECTORYcompiler installation override (normally remembered by rbit setup)
--compile-timeout SECONDS120.0limit for each compiler or resource-compiler step (default: 120)
--cleanup-timeout SECONDS10.0limit for stopping each isolated execution lane and its wineserver (default: 10)

rbit discover clean

Preview or remove one advanced discovery campaign's reusable state.

rbit discover clean [-h] [--state-directory DIRECTORY] [--preview] [--all-requests] request
ArgumentDefaultDescription
requestrequest JSON whose state should be removed
ArgumentDefaultDescription
--state-directory DIRECTORY.reprobit-discoverycampaign state beside the request (default: .reprobit-discovery)
--previewshow what would be removed without changing anything
--all-requestsremove state shared by every request named in its ownership marker

rbit discover grind

Use this for a project's initial mismatch. Search a bounded, project-wide set of low-cost adjustments using project-owned reference .obj files. The default is a preview. Saved local progress does not prove the complete project; only a fresh byte-exact result does. For a later regression in an already-exact project, use rbit repair instead.

rbit discover grind [-h] [--accept-exact | --accept-progress] [--reference-object TU=PROJECT_PATH] [--max-symbols COUNT] [--expert-plan PROJECT_RELATIVE_PATH] [--jobs COUNT] [--backend {auto,posix_wine_v1,windows_native_v1}] [--wine PATH_OR_NAME] [--wineserver PATH_OR_NAME] [--toolchain-root DIRECTORY] [--compiler-transport PATH] [--resource-transport PATH] [--initialization-timeout SECONDS] [--compile-timeout SECONDS] [--link-timeout SECONDS] [--cleanup-timeout SECONDS] [project]
ArgumentDefaultDescription
project.ReproBit project to search (default: .)
ArgumentDefaultDescription
--accept-exactsave only if a fresh run reproduces the complete project exactly
--accept-progresssave bounded, locally proven function adjustments even while the complete project still differs
--reference-object TU=PROJECT_PATHpair a translation unit with a reference .obj; repeat for additional units
--max-symbols COUNT8maximum project functions to try in deterministic order (default: 8; max: 64)
--expert-plan PROJECT_RELATIVE_PATHrun one deliberately authored per-symbol plan instead of project-wide discovery
--jobs COUNTmaximum parallel build workers (default: the CPUs this process may use, at most 8)

Shared: see advanced execution options.

rbit state status

Show retained runs, cache, reports, active leases, and disk usage.

rbit state status [-h] [project]
ArgumentDefaultDescription
project.project directory (default: .)

rbit report

Validate JSON and render self-contained HTML.

rbit report [-h] [--html PATH] input
ArgumentDefaultDescription
inputcanonical report.json to validate and render
ArgumentDefaultDescription
--html PATHHTML output path (default: replace the input suffix with .html)

rbit cmake-module

Print the packaged CMake module path.

rbit cmake-module [-h] [--file]
ArgumentDefaultDescription
--fileprint the packaged ReproBit.cmake file instead of its directory

advanced execution options

Defaults are suitable for people; these controls are mainly for CI and unusual hosts.

Accepted by rbit repair, rbit build, rbit verify, rbit discover grind. Flags a command's handler does not use are omitted from that command (for example --cold outside build).

ArgumentDefaultDescription
--backend {auto,posix_wine_v1,windows_native_v1}autoexecution backend (default: select from the host platform)
--wine PATH_OR_NAMEwinePOSIX Wine executable (default: wine from PATH)
--wineserver PATH_OR_NAMEwineserverPOSIX wineserver executable (default: wineserver from PATH)
--toolchain-root DIRECTORYcompiler installation override (normally remembered by rbit setup)
--compiler-transport PATHPOSIX transport selector for the locked compiler (paired with --resource-transport)
--resource-transport PATHPOSIX transport selector for the locked resource compiler
--initialization-timeout SECONDS600.0limit for each isolated execution-lane initialization (default: 600)
--compile-timeout SECONDS600.0limit for each compiler or resource-compiler step (default: 600)
--link-timeout SECONDS900.0limit for each librarian or linker producer (default: 900)
--cleanup-timeout SECONDS10.0limit for stopping each isolated execution lane and its wineserver (default: 10)