CLI reference
Every command and option of the released ohx command, read from its own parser.
Generated from the argument parser of ohx 0.1.1, so every command and option below exists in that release. ohx --help and ohx <command> --help print the same. Global options: --version and --help.
Exit codes
| Code | Meaning |
|---|---|
0 | Success: READY or NO REGRESSIONS |
10 | A valid result that does not pass: BLOCKED, UNKNOWN, INVALID or STALE |
2 | Usage or input error |
1 | Internal failure |
ohx doctor#
Check the local environment OpenHarnX needs.
ohx doctor [-h]
Checks Python (3.12 or newer), git and the platform. Exit 0 when every required check passes, 10 when one fails. In 0.1.1 it does not check srt or Node; ohx verify --sandbox srt reports a missing srt itself.
ohx init#
Create the OpenHarnX store for this repository.
ohx init [-h] [--lock-tests] [--sandbox {auto,srt,none}]| --lock-tests | Make the existing test suite the contract (no contract file to write) |
| --sandbox {auto,srt,none} | Where the suite's baseline runs (with --lock-tests) Default: auto. |
Creates the evidence store for the repository under ~/.openharnx (or OHX_HOME). With --lock-tests, the suite as it is now becomes the contract and its per-test results become the baseline. Run it again to accept a deliberate test change.
ohx hook install#
Add the Stop hook to .claude/settings.local.json.
ohx hook install [-h]
Adds a Stop hook to .claude/settings.local.json in the current repository. Keep that file out of git: it holds paths on your machine.
ohx contract accept#
Validate and accept a contract TOML file.
ohx contract accept [-h] [--sandbox {auto,srt,none}] file| file | Argument. |
| --sandbox {auto,srt,none} | Where the regression baseline runs Default: auto. |
Validates a contract TOML file you wrote and accepts it: the acceptance tests it names are copied into the store and the regression baseline is recorded.
ohx contract new#
Write a contract from project defaults.
ohx contract new [-h] --title TITLE --summary SUMMARY [--mode {bugfix,task}] --acceptance ACCEPTANCE [--accept] [--sandbox {auto,srt,none}]| --title TITLErequired | |
| --summary SUMMARYrequired | One line; becomes the changelog entry |
| --mode {bugfix,task} | Default: bugfix. |
| --acceptance ACCEPTANCErequired | Test file or folder that proves the change; locked away at acceptance Repeatable. |
| --accept | Accept it straight away |
| --sandbox {auto,srt,none} | Where the regression baseline runs when accepting Default: auto. |
Writes contracts/NNNN-<title>.toml from ohx.toml and the acceptance tests you name. --acceptance can be given more than once. --mode defaults to bugfix. With --accept the contract is accepted at once.
ohx verify#
Verify the current candidate against the contract.
ohx verify [-h] [--sandbox {auto,srt,none}] [--json]| --sandbox {auto,srt,none} | Default: auto. |
| --json |
Runs every check of the accepted contract against the working tree and prints the report. Exit 0 for READY and NO REGRESSIONS, 10 for BLOCKED, UNKNOWN, INVALID or STALE, 2 for a usage error such as --sandbox srt without srt installed.
ohx approve-tests#
Sign an approval of a commit's intended test changes (any platform).
ohx approve-tests [-h] [--out OUT] [rev]
| rev | The commit to approve (default HEAD) Default: HEAD. |
| --out OUT | Write the signature to this file instead of a git note |
Signs "test changes approved for commit X" with your SSH key and stores the signature as a git note in refs/notes/ohx-approvals, or in a file with --out.
ohx history#
What the gate would have said about each change already merged.
ohx history [-h] [--last LAST] [--branch BRANCH] [--agents-only] [--config CONFIG] [--sandbox {auto,srt,none}] [--out OUT]| --last LAST | How many commits back (default 20) Default: 20. |
| --branch BRANCH | The branch to walk (default: the checked-out one) |
| --agents-only | Only changes by coding agents |
| --config CONFIG | An ohx.toml to lend to commits that have none |
| --sandbox {auto,srt,none} | Default: auto. |
| --out OUT | Folder for history.md and .json Default: ohx-history. |
Walks recent commits and writes what the gate would have said about each to ohx-history/history.md and .json. Commits made by coding agents are marked.
ohx gate#
CI: judge the checked-out change against its base commit.
ohx gate [-h] --base BASE [--sandbox {auto,srt,none}] [--out OUT] [--contract CONTRACT] [--home HOME] [--approve-tests-label APPROVE_TESTS_LABEL] [--approval-file APPROVAL_FILE]| --base BASErequired | Base commit or ref (the trusted side) |
| --sandbox {auto,srt,none} | Default: auto. |
| --out OUT | Folder for report.json and report.md Default: ohx-gate. |
| --contract CONTRACT | A contract file in the base commit, instead of its tests |
| --home HOME | Keep the evidence store here (default: a throwaway one) |
| --approve-tests-label APPROVE-TESTS-LABEL | GitHub label with which a maintainer approves the pull request's test changes |
| --approval-file APPROVAL-FILE | A signature from `ohx approve-tests --out`, instead of git notes |
For CI. Judges the checked-out change against --base: the base's tests run as locked copies, the base's ohx.toml is the policy, and nothing the change adds to them is used. Writes report.json, report.md and evidence/ to --out.
ohx audit#
Who did what and touched what, from the evidence store.
ohx audit [-h]
Lists who did what from the evidence store: contracts accepted, suites locked, verifications and the files they touched.
ohx report#
Show the latest report.
ohx report [-h] [--json]
| --json |
Prints the latest report for the repository, re-checking it against the store. A report made before the files changed shows as STALE.
ohx bug new#
Report a bug; the agent investigates read-only.
ohx bug new [-h] [--sandbox {srt,none}] symptom| symptom | What is wrong, as a user would report it |
| --sandbox {srt,none} | Default: srt. |
ohx bug show#
Print the proposal and the proposed tests in full.
ohx bug show [-h] bug
| bug | Argument. |
ohx bug approve#
Accept the proposed rule and tests as the contract.
ohx bug approve [-h] bug
| bug | Argument. |
ohx bug fix#
Assign the contract to the agent and verify.
ohx bug fix [-h] [--sandbox {srt,none}] [--attempts ATTEMPTS] [--budget BUDGET] bug| bug | Argument. |
| --sandbox {srt,none} | Default: srt. |
| --attempts ATTEMPTS | Default: 2. |
| --budget BUDGET | USD cap across this bug's runs Default: 2. |
ohx trace init#
Split sources into numbered units (merges markings).
ohx trace init [-h] [--out OUT] sources [sources ...]
| sources | BRD, decisions or other requirement files |
| --out OUT | Default: trace.toml. |
ohx trace check#
Report every unit; blocks on any gap.
ohx trace check [-h] [--trace TRACE] [--run] [--all]
| --trace TRACE | Default: trace.toml. |
| --run | Run the linked tests |
| --all | Also list covered units |
ohx trace approve#
Approve the units marked context or excluded.
ohx trace approve [-h] [--trace TRACE] [--yes]
| --trace TRACE | Default: trace.toml. |
| --yes |
ohx store check#
Verify the hash chain and record digests.
ohx store check [-h] [--signer SIGNER]
| --signer SIGNER | Expected signing key: a public key file or a SHA256 fingerprint; repeatable Repeatable. |
Verifies the hash chain, every record's digest and the signatures. --signer pins the key that must have signed.