CLI reference¶
harness 2.0.1 exposes 80 commands. Every command accepts --help.
Exit codes are documented in exit codes.
Global options go before the command name (harness --no-json run list):
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--version |
flag | no | false | Print the harness version and exit |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) | |
--install-completion |
flag | no | Install completion for the current shell. | |
--show-completion |
flag | no | Show completion for the current shell, to copy it or customize the installation. |
| Command | Summary |
|---|---|
harness init |
Create .harness/project.yaml for a repository, using the detected technology profiles, make Git ignore .harness/ (in... |
harness inspect |
Detect the technology profiles of a repository (read-only), with confidence and evidence. |
harness doctor |
Check the local environment (Python and Git required; Node.js and npm reported as NOT_APPLICABLE when absent; Git... |
harness do |
Make a change from TEXT in one command: create the task (the text is its intent and, without --criterion, its... |
harness check |
Run the validators of the gate and the enabled diff checks on the workspace, without recording anything... |
harness status |
Show the full status projection of a run: phases, validations, findings, gate, human decision, event-chain check and... |
harness trace |
Export the trace of a run as Markdown, JSON, JSONL, SARIF or a GitLab Code Quality report (codequality: the findings,... |
harness verify |
Verify the record of a run (or of every run): the event chain, the head of the chain against its anchor outside... |
harness export |
Export a run as a portable evidence bundle: its event chain, records, every artifact they reference and a manifest... |
harness verify-approval |
Check in CI that the range --base..--head is a ChangeSet a person approved: recompute its ChangeSet digest from the... |
harness gc |
Apply the retention settings to runs that ended (closed, cancelled or rejected) longer ago than them:... |
harness inbox |
List the runs of the project that wait for a person, oldest first: a decision in DECISION (gate status, digest,... |
harness metrics |
Local metrics of the governed runs, with zero model calls: tokens (input, output, cache) and cost by agent, model,... |
harness registry |
List the projects whose run registry lives in the state directory (runtime.stateDir: auto, $HARNESS_STATE_DIR or... |
harness review-code |
Review a change with the review panel outside a governed run: reviewers by domain over diff slices, the layered rule... |
harness retrospect |
Derive non-mutating observations and recommendations from a closed run. |
harness config validate |
Validate the project configuration and print the resolved profiles, workflow, validators, capabilities and policies,... |
harness config lint |
Report contradictions between the harness configuration and the agent instruction files (AGENTS.md, CLAUDE.md,... |
harness task create |
Validate a task file (YAML or JSON) and persist it as a versioned task. |
harness task list |
List the tasks persisted in the project. |
harness task show |
Show one persisted task. |
harness task questions |
Show the clarification questions INTENT asked about a task: the open request (asked about the current revision of the... |
harness task clarify |
Answer the open clarification questions of a task and store the revised task. |
harness task confirm |
Confirm the operational contract of a task's current revision, bound to its digest (intake.operationalContract). |
harness run start |
Create a run for a task and execute the normative phases until a stop condition. |
harness run continue |
Resume a run from its persisted state, for example after fixing the environment or after REQUEST_CHANGES. |
harness run cancel |
Cancel a run and terminate its active process group. |
harness run cleanup |
Remove the worktree of a finished isolated run (run start --isolate worktree). |
harness run quarantine |
Keep the changes of a run that stopped without approval as a quarantined patch and restore the workspace to its... |
harness run list |
List the runs of the project, newest first. |
harness gate decide |
Record a human decision bound to the current ChangeSet digest. |
harness evidence list |
List the evidence records of a run with their artifact references and digests. |
harness evidence attach |
Attach evidence. |
harness findings list |
List the structured findings of a run with severity, rule and location. |
harness memory add |
Record a memory entry with its provenance. |
harness memory list |
List the memory records of the project with their status: active, superseded, expired, unapproved, limit or... |
harness memory manifest |
Show the context manifest recorded for a run: the records it applied, their digest and the candidates it excluded... |
harness memory approve |
Approve a proposed record. |
harness memory invalidate |
Invalidate a record without deleting it: it stops entering any context and the actor and the reason stay on record. |
harness recommendation list |
List the retrospective recommendations of a run with the decision recorded for each. |
harness recommendation decide |
Accept, edit or reject a retrospective recommendation. |
harness plugins list |
List the built-in extensions and the external plugin protocol version. |
harness benchmark run |
Run the synthetic microbenchmarks (hashing, transitions, gates, events, artifacts, process launch). |
harness benchmark scenarios |
Compare a direct patch-and-test path with the complete governed path on generated Python and Node.js projects. |
harness api serve |
Serve the local API and web dashboard. |
harness artifact show |
Print an artifact's content after verifying its digest, or its descriptor with --describe. |
harness exceptions list |
List the exceptions of the project (review.exceptions): who granted each, on which run and digest, its scope,... |
harness rules health |
Show how each rule and validator behaved across the runs of the project: how often it fired, blocked a gate, was... |
harness outcome record |
Link something that happened after a run (an incident, a revert, a hotfix, a regression) to it. |
harness outcome list |
List the outcomes linked to the runs of the project, oldest first. |
harness plan show |
Show the decomposition PLANNING proposed for a run (planning.decomposition), its digest, its status and the... |
harness plan decide |
Approve or reject the proposed decomposition, bound to its digest. |
harness acceptance show |
Show the acceptance tests proposed for a run (verification.acceptanceTests), their digest, their status and, once... |
harness acceptance decide |
Approve or reject the proposed acceptance tests, bound to their digest. |
harness acceptance dispute |
Decide a dispute of the frozen acceptance tests (verification.acceptanceTests.disputes): a run whose VERIFICATION... |
harness budget show |
Show the usage of a run and of its task (reported tokens and cost, measured wall time of the agent calls) against the... |
harness budget raise |
Raise a budget limit of a run blocked with budget.exceeded; the raise is recorded on the run's event chain with the... |
harness routing calibrate |
Report the cost per approved task of every routing decision recorded in the project (agentRouting), by provider... |
harness agent-contract schema |
Print the JSON Schema of the request contract (what a parent sends an agent call), of the response contract (what the... |
harness agent-contract validate |
Validate a JSON file against a contract; output is the JSON an agent prints, checked against the limits of its call... |
harness agent-contract scripts |
List the scripts and commands agents may call as black boxes, or show the contract (invocation, inputs, outputs,... |
harness agent-contract calls |
Show the agent calls of a run, the iterations each agent used against its cap and, with --kind (and --iteration),... |
harness pr publish |
Post the decision brief of a run on a pull or merge request (one comment per run, updated when published again) and... |
harness pr create |
Open a pull or merge request from the closure branch of a run (push the branch first), with the repository's pull... |
harness pr status |
Set the commit status governed-harness from a run: success once it closed approved, pending while it waits for a... |
harness pr forge |
Show the forge the workspace resolves to (delivery.forge or the origin remote), its API URL, transport and the... |
harness verification show |
Show the verification plan of a run (the rung each criterion requires, the rungs this environment reaches and why),... |
harness verification decide |
Decide on a run whose preflight is UNAVAILABLE: continue it uncertified for what this environment cannot verify... |
harness standards show |
Show the language standards packs: the detected and effective packs (repository overrides applied), their tools and... |
harness architecture show |
Show the architecture of the project: the configured section, whether the project is new or existing, the cached... |
harness architecture decide |
Decide the architecture, bound to the digest of the proposal: approve or reject the layer rules a survey inferred... |
harness architecture refresh |
Mark the cached architecture survey stale: the next run surveys the project again (one call). |
harness project show |
Show what the harness detects about the project, deterministically and without an agent call: new or existing (and... |
harness mcp serve |
Serve the harness to an agent session over stdio (Model Context Protocol, JSON-RPC 2.0, one message per line). |
harness review |
Show the decision brief of a run: what was asked, what changed, the risks with file and line, what was verified on... |
harness review verify |
Check the review evidence of a commit (refs/harness/review/pass/SHA or pass-warn) without calling any model: the... |
harness review variance |
Run the same review several times without cache and report its variance: verdict stability, how often each finding... |
harness review rules show |
Show the effective review rule catalog: the rules of the three layers (built-in, language packs, project) after... |
harness review rules sync |
Write the generated rules block of every project reviewer (.harness/review/agents) from the catalog, between its... |
harness review hook install |
Install a pre-push hook that runs harness review-code --mode hook: a FAIL or UNKNOWN verdict, or a base that cannot... |
harness init¶
Create .harness/project.yaml for a repository, using the detected technology profiles, make Git ignore .harness/ (in .git/info/exclude, so the tree stays clean) and write an example task. Prints the detected profiles and the next commands.
harness init [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Project directory | |
--force |
flag | no | false | Replace an existing project configuration |
--gitignore, --no-gitignore |
flag | no | --gitignore | Make Git ignore .harness/ (state, artifacts and copies of the code live there) |
--ignore-file |
exclude | gitignore |
no | exclude |
Where the .harness/ entry goes: exclude writes the repository's .git/info/exclude, so an existing repository's tree stays clean (the .gitignore outside a Git repository); gitignore writes the project's .gitignore |
--example-task, --no-example-task |
flag | no | --example-task | Write an example task to .harness/task.example.yaml |
--agent-skills |
flag | no | false | Also write the skill of the governed flow for Claude Code (.claude/skills/harness/SKILL.md) and Codex (.codex/skills/harness/SKILL.md) |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness inspect¶
Detect the technology profiles of a repository (read-only), with confidence and evidence.
harness inspect [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness doctor¶
Check the local environment (Python and Git required; Node.js and npm reported as NOT_APPLICABLE when absent; Git identity reported) and, with --path, the project: its configuration, the agent CLI of the configured provider on PATH, the agent sandbox mechanism, the validators, the baseline commit and whether .harness/ is ignored by Git. Each check that is not PASSED says how to fix it. Exit code 2 when a required check FAILED; a WARNING does not fail.
harness doctor [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Also validate the project in this directory | |
--install-hooks |
flag | no | false | Run the hook installation command the project declares (environment.gitHooks.install) before the checks |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness do¶
Make a change from TEXT in one command: create the task (the text is its intent and,
without --criterion, its acceptance criterion), run it and, on a terminal, answer INTENT's
questions and show the decision brief and ask for the decision. No task file is needed.
Small, risk-free tasks take the fast lane (friction.fastLane). With --pre-approve the
approval you give now is applied only when the gate passed, there is no risk factor and the
task is size S. Exit codes as run start: 0 closed, 4 a decision is pending, 6 stopped.
harness do [OPTIONS] {text}
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
text |
str | yes | ||
--criterion |
str | no | An acceptance criterion (repeatable; default: the text itself) | |
--owned |
str | no | A workspace path the change may touch (repeatable) | |
--title |
str | no | Task title (default: first line) | |
--provider |
str | no | Agent provider id; defaults to the project agentProvider | |
--pre-approve |
flag | no | false | Approve in advance (friction.preAuthorization): applied at DECISION only if the gate passed, the ChangeSet has no risk factor and the task is size S |
--pre-approve-hours |
int range | no | Validity of the pre-authorised approval | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--interactive, --no-interactive |
flag | no | --interactive | On a terminal, answer the questions and decide in the same command |
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness check¶
Run the validators of the gate and the enabled diff checks on the workspace, without
recording anything (runtime.gateContract). The agent can run it before it finishes; the
implement request carries the exact command. Exit 0 when every mandatory validator passes
and no enforced check reports a blocking problem, 6 otherwise.
harness check [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | no | Run whose task and baseline the diff checks use (default: the latest run that wrote a check state) | |
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness status¶
Show the full status projection of a run: phases, validations, findings, gate, human decision, event-chain check and metrics.
harness status [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | no | latest |
Run (execution) identifier, latest or a unique prefix such as run_1a2b |
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness trace¶
Export the trace of a run as Markdown, JSON, JSONL, SARIF or a GitLab Code Quality
report (codequality: the findings, with the same fingerprints as SARIF). Under
governance.verifyRecords: true the run is verified first (as harness verify) and a run
that does not verify is not exported (exit code 6).
harness trace [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | no | latest |
Run (execution) identifier, latest or a unique prefix such as run_1a2b |
--format |
str | no | markdown |
markdown, json, jsonl, sarif or codequality |
--output |
path | no | Write to this file instead of standard output | |
--path |
path | no | Project directory |
harness verify¶
Verify the record of a run (or of every run): the event chain, the head of the chain
against its anchor outside .harness (governance.chainAnchor), every record that has an
event against that event, the execution's pointers and every referenced artifact against its
digest. Prints a report and never repairs anything. With --bundle, verify an evidence bundle
of harness export instead: its entries against the manifest, the event chain, the artifacts
and the decision records. Exit code 0 when everything verifies, 6 when any check fails (the
report's hint then names the next commands for each run that does not verify), 3 for an
unknown run or bundle.
harness verify [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | no | Run (execution) identifier; without it, every run of the workspace | |
--bundle |
file | no | Verify a portable evidence bundle instead (no workspace needed) | |
--path |
path | no | Project directory |
harness export¶
Export a run as a portable evidence bundle: its event chain, records, every artifact they
reference and a manifest with the digest of each entry. harness verify --bundle and
harness verify-approval --bundle check it without the workspace. A run whose event chain
does not verify is not exported (exit code 5; 6 under governance.verifyRecords when the
record does not verify).
harness export [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--bundle |
file | yes | Write the portable evidence bundle (tar.gz) here | |
--run |
str | no | latest |
Run (execution) identifier, latest or a unique prefix such as run_1a2b |
--path |
path | no | Project directory |
harness verify-approval¶
Check in CI that the range --base..--head is a ChangeSet a person approved: recompute its ChangeSet digest from the two revisions and require an unexpired APPROVE or APPROVE_EXCEPTION bound to that digest in a bundle (or the workspace record). Any other change in the range fails. Exit code 0 when it passes, 5 when no approval matches.
harness verify-approval [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--base |
str | yes | Revision the change starts from (the pull request base) | |
--head |
str | no | HEAD |
Revision to verify (the merged tree) |
--bundle |
path | no | Evidence bundle with the approval (repeatable) | |
--workspace, --no-workspace |
flag | no | --workspace | Also look for the approval in the workspace's .harness/state.db |
--path |
path | no | Repository directory |
harness gc¶
Apply the retention settings to runs that ended (closed, cancelled or rejected) longer
ago than them: retention.artifactDays deletes the run's artifacts that no kept run uses and
records a retention.artifacts.pruned event; retention.eventDays removes the run, its
events, records and artifacts. Open runs and memory records are never touched. Without
--apply only the report is printed.
harness gc [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--apply |
flag | no | false | Delete what the report lists; without it nothing is deleted |
--path |
path | no | Project directory |
harness inbox¶
List the runs of the project that wait for a person, oldest first: a decision in DECISION (gate status, digest, blocking findings, the risk factors an APPROVE must acknowledge), answers to clarification questions in INTENT, and every other wait before DECISION (kind plan, decomposition, acceptance, acceptance-dispute, architecture, contract, deferred or preflight, with the digest it binds to), each with the next command. With --approve, --reject, --request-changes, --decisions or --batch it records several decisions, each bound to its own ChangeSet digest (a batch file may list acknowledgeRisks per decision): a stale digest or a refused decision is reported for that run (the others are recorded) and the command exits 5 when any was refused.
harness inbox [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) | |
--approve |
str | no | Batch: APPROVE a run as RUN=sha256:DIGEST, the digest the inbox shows (repeatable) | |
--reject |
str | no | Batch: REJECT a run as RUN=sha256:DIGEST (repeatable) | |
--request-changes |
str | no | Batch: REQUEST_CHANGES on a run as RUN=sha256:DIGEST (repeatable) | |
--decisions |
file | no | Batch file (YAML or JSON): a list of run, decision, changeSetDigest and an optional rationale | |
--batch |
flag | no | false | On a terminal: decide every pending decision of the inbox one after the other |
--rationale |
str | no | Batch: the rationale recorded with each decision | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--path |
path | no | Project directory |
harness metrics¶
Local metrics of the governed runs, with zero model calls: tokens (input, output, cache) and cost by agent, model, task and phase, models used, lines by agent invocation and by person, issues resolved and features delivered, time per task, phase, agent call and human wait, quality, friction against the targets per size and daily and weekly trends. Costs of providers that report only tokens are estimated from the price table and labelled estimated. The HTML file is self-contained (inline CSS and SVG, nothing fetched). No per-person indicator is computed.
harness metrics [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--format |
str | no | html, md, json, csv (one row per run) or prometheus; printed, or written to --output. Without it, metrics.json, metrics.md and metrics.html are written to --output-dir | |
--output |
path | no | File for --format | |
--output-dir |
path | no | Directory of the three files written without --format (default .harness/metrics) | |
--open |
flag | no | false | Open the HTML report in the default browser |
--since |
str | no | Only runs created since DATE (YYYY-MM-DD, ISO 8601, 7d, 2w, 12h) | |
--task |
str | no | Only the runs of this task | |
--model |
str | no | Only agent calls of this model | |
--agent |
str | no | Only agent calls of this agent provider id | |
--all-repos |
flag | no | false | Every repository of the run registry (runtime.stateDir), not only this one |
--prices |
file | no | Price table (YAML or JSON, USD per million input, output and cache tokens by model id) for providers that report tokens without a cost; overrides metrics.prices | |
--narrative |
flag | no | false | Add a narrative summary: one call to metrics.narrative.command, on demand |
--path |
path | no | Project directory |
harness registry¶
List the projects whose run registry lives in the state directory
(runtime.stateDir: auto, $HARNESS_STATE_DIR or the user's data directory) with their
latest runs: the runs of several repositories in one place.
harness registry [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness review-code¶
Review a change with the review panel outside a governed run: reviewers by domain over diff slices, the layered rule catalog, a fixed output contract and a verdict the harness recomputes. Rules a tool verifies never reach a model; reviewers run only on their signals; answers are cached. A passing review is recorded as refs/harness/review/pass/SHA (or pass-warn). Exit code 6 when the verdict is FAIL or UNKNOWN (under review.panel.mode enforce) or when hook mode cannot fetch the base.
harness review-code [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--mode |
str | no | manual |
manual: the branch against its base; hook: the same, fetching the base first (a failed fetch aborts); staged: the index against HEAD |
--base |
str | no | Base branch or commit; default: the pull or merge request base of the CI, the branch convention (review.panel.baseBranches), then the default branch | |
--head |
str | no | HEAD |
The commit to review (manual and hook) |
--provider |
str | no | Provider of the reviewers (an agentProviders id or simulated) | |
--fallback-provider |
str | no | Provider of the one retry after an invalid answer | |
--model |
str | no | Force one model for every reviewer | |
--skip |
str | no | A reviewer id to skip (repeatable) | |
--pull-request |
int | no | Pull or merge request number for the comment (default: from the CI environment) | |
--comment, --no-comment |
flag | no | Post one comment per passing result on the pull or merge request (default: review.panel.comment) | |
--cache, --no-cache |
flag | no | --cache | Use the review cache |
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness retrospect¶
Derive non-mutating observations and recommendations from a closed run. Nothing is applied automatically.
harness retrospect [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | no | latest |
Run (execution) identifier, latest or a unique prefix such as run_1a2b |
--path |
path | no | Project directory |
harness config validate¶
Validate the project configuration and print the resolved profiles, workflow,
validators, capabilities and policies, the settings that are declared but not applied
(declarative) and a warning for each one the project relies on (warnings).
harness config validate [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness config lint¶
Report contradictions between the harness configuration and the agent instruction files
(AGENTS.md, CLAUDE.md, .cursorrules, .cursor/rules, .github/copilot-instructions.md): tool
versions, coverage thresholds, statements about the tests and instructions to bypass a
control (--no-verify, a forced push, git add -A). Each conflict names the source that wins by
instructions.precedence. Exit 6 when there is any issue.
harness config lint [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness task create¶
Validate a task file (YAML or JSON) and persist it as a versioned task. A task needs
at least one acceptance criterion (exit code 2 otherwise), except under
intake.criteriaPolicy: enforce: there a task without criteria is stored with
criteriaPending: true and INTENT asks for its criteria (rule C0). Under
governance.pinTaskRevision: true a task id that has an open run is refused with exit code 5:
revise it with task clarify during INTENT or use a new id.
harness task create [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--file |
file | yes | Task file (YAML or JSON) | |
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness task list¶
List the tasks persisted in the project.
harness task list [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness task show¶
Show one persisted task.
harness task show [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--task |
str | yes | Task identifier (taskId) | |
--path |
path | no | Project directory |
harness task questions¶
Show the clarification questions INTENT asked about a task: the open request (asked about the current revision of the task), every earlier request and the recorded answers.
harness task questions [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--task |
str | yes | Task identifier (taskId) | |
--path |
path | no | Project directory |
harness task clarify¶
Answer the open clarification questions of a task and store the revised task. Run
harness run continue afterwards to assess the revision in INTENT. An unknown question id
or an empty answer exits with 2, no open request with 3, and a task with a run past INTENT
or an actor id of an agent, validator or the harness with 5.
harness task clarify [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--task |
str | yes | Task identifier (taskId) | |
--file |
file | yes | Answers file (YAML or JSON): answers by question id, optional criteria and requirement changes | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--path |
path | no | Project directory |
harness task confirm¶
Confirm the operational contract of a task's current revision, bound to its digest
(intake.operationalContract). Under enforce INTENT waits for it; then harness run
continue. With --pre-approve the same act records an approval in advance bound to the
contract digest and the condition gate passed, no risk factor, size S. A stale digest, a
non-human actor or --pre-approve without friction.preAuthorization.mode: allow exits 5.
harness task confirm [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--task |
str | yes | Task identifier (taskId) | |
--digest |
str | yes | Digest of the operational contract shown by task questions | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--pre-approve |
flag | no | false | Under friction.preAuthorization: also approve the run in advance, applied at DECISION only if the gate passed, the ChangeSet has no risk factor and the task is size S; otherwise you are asked as usual |
--pre-approve-hours |
int range | no | Validity of the pre-authorised approval in hours (default friction.preAuthorization.defaultHours, at most maxHours) | |
--rationale |
str | no | `` | Why you approve in advance (recorded with --pre-approve) |
--path |
path | no | Project directory |
harness run start¶
Create a run for a task and execute the normative phases until a stop condition. Exit code 4 means the automated phases finished and a human decision is pending; 6 means a validation, policy or blocking condition stopped the run. With --isolate worktree a branch or worktree directory that already exists stops the run (exit 6); nothing is reset or deleted.
harness run start [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--task |
str | yes | Task identifier (taskId) | |
--provider |
str | no | Agent provider id; defaults to the project agentProvider | |
--isolate |
str | no | worktree: run in a Git worktree of its own on a new branch from the updated base branch; none: in place (default: workspace.isolation.mode) | |
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness run continue¶
Resume a run from its persisted state, for example after fixing the environment or after REQUEST_CHANGES.
harness run continue [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness run cancel¶
Cancel a run and terminate its active process group. The cancellation is recorded as an event.
harness run cancel [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--path |
path | no | Project directory |
harness run cleanup¶
Remove the worktree of a finished isolated run (run start --isolate worktree). Only a
worktree the harness created and without uncommitted changes is removed; its branch is
kept. Anything else exits 5.
harness run cleanup [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--path |
path | no | Project directory |
harness run quarantine¶
Keep the changes of a run that stopped without approval as a quarantined patch and
restore the workspace to its baseline (governance.stopTheLine). This releases a line
blocked by stopTheLine: block. A run that is closed or still open for a decision is
refused (exit 5).
harness run quarantine [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--path |
path | no | Project directory |
harness run list¶
List the runs of the project, newest first.
harness run list [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Project directory |
harness gate decide¶
Record a human decision bound to the current ChangeSet digest. A decision for a stale
digest, or APPROVE over a gate that did not pass, is rejected with exit code 5. On a
terminal, omitting --decision, --change-set-digest or --rationale shows the decision brief,
asks for the missing values and asks the person to type the start of the digest the decision
binds to; a digest that is not confirmed records nothing (exit 5). Without a terminal the
three options are required (exit 2). Under governance.confirmDecisionDigest: true the
same confirmation is asked on a terminal even when every option is given. An actor id of an
agent, validator or the harness is refused with exit 5; without --actor the decider is the
Git user under governance.deciderIdentity: git (human.local, with a warning, when Git has
no identity).
harness gate decide [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--decision |
APPROVE | REJECT | REQUEST_CHANGES | APPROVE_EXCEPTION |
no | Human decision; asked interactively when omitted on a terminal | |
--change-set-digest |
str | no | Current ChangeSet digest shown by status or review (sha256:...); confirmed interactively when omitted on a terminal | |
--rationale |
str | no | Justification recorded with the decision; asked interactively when omitted | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--continue, --no-continue |
flag | no | --continue | Resume the run after recording the decision |
--expires-in |
str | no | APPROVE_EXCEPTION under review.exceptions: validity such as 14d, 36h or 2w (default review.exceptionDays) | |
--expires-at |
str | no | APPROVE_EXCEPTION: ISO 8601 instant the exception expires | |
--scope |
str | no | APPROVE_EXCEPTION: findings covered, as rule or rule:path (repeatable; default: the blocking findings of the gate, by fingerprint) | |
--alternative-evidence |
str | no | APPROVE_EXCEPTION: evidence that compensates for the blocking findings | |
--follow-up |
str | no | APPROVE_EXCEPTION: issue or task that will remove the exception | |
--interactive, -i |
flag | no | false | Show the decision brief and confirm the ChangeSet digest even when every option is given |
--acknowledge-risk |
str | no | APPROVE or APPROVE_EXCEPTION under verification.riskFactors: a risk factor of the ChangeSet the decider acknowledges (repeatable; required for every factor whose action is acknowledge) | |
--check |
str | no | Under review.manualChecklist: a checklist item the person verified (repeatable); APPROVE needs every item of the run | |
--change-request |
str | no | REQUEST_CHANGES under review.structuredChanges: a blocking item as 'description::condition' where the condition is test:NODE_ID (a pytest node id), absent:REGEX or text (repeatable) | |
--path |
path | no | Project directory |
harness evidence list¶
List the evidence records of a run with their artifact references and digests.
harness evidence list [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | no | latest |
Run (execution) identifier, latest or a unique prefix such as run_1a2b |
--path |
path | no | Project directory |
harness evidence attach¶
Attach evidence. With --run and --item D-CRITERION, close a deferred verification with a JUnit, SARIF or CI status report (bound to the item's ChangeSet digest and commit; an expired item exits 5). With --manual, store a person's attachment bound to the run's ChangeSet (and to a checklist item with --item), or to a task revision as intake context the agent receives (--task).
harness evidence attach [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--file |
file | yes | File to attach | |
--run |
str | no | Run the evidence is about | |
--task |
str | no | Task the attachment is intake context of (with --manual) | |
--item |
str | no | Deferred item (D-CRITERION) to close, or checklist item | |
--manual |
flag | no | false | A person's attachment (screenshot, video, log) instead of a test or CI report |
--format |
str | no | auto |
auto, junit, sarif or ci-status (deferred items) |
--case |
str | no | Only the JUnit test cases whose name contains this text | |
--commit |
str | no | Commit the evidence is about (checked against the item's) | |
--note |
str | no | What the attachment shows | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--path |
path | no | Project directory |
harness findings list¶
List the structured findings of a run with severity, rule and location.
harness findings list [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | no | latest |
Run (execution) identifier, latest or a unique prefix such as run_1a2b |
--path |
path | no | Project directory |
harness memory add¶
Record a memory entry with its provenance. NORMATIVE, PROJECT and RETROSPECTIVE entries enter a context only once approved.
harness memory add [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--level |
NORMATIVE | PROJECT | TASK | EPHEMERAL | RETROSPECTIVE |
yes | Scope of the record | |
--key |
str | yes | Stable name of the record within its level | |
--value |
str | yes | JSON object, or plain text stored under the key 'text' | |
--task |
str | no | Task identifier; required for TASK | |
--run |
str | no | Run identifier; required for EPHEMERAL | |
--valid-until |
str | no | ISO 8601 instant after which the record no longer applies | |
--supersedes |
str | no | Identifier of the record this one replaces | |
--sensitive |
flag | no | false | Withhold the value from the context manifest and the agent |
--approve |
flag | no | false | Record the entry as approved by the acting person |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--path |
path | no | Project directory |
harness memory list¶
List the memory records of the project with their status: active, superseded, expired, unapproved, limit or out_of_scope.
harness memory list [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--task |
str | no | Evaluate the status for this task | |
--run |
str | no | Evaluate the status for this run | |
--path |
path | no | Project directory |
harness memory manifest¶
Show the context manifest recorded for a run: the records it applied, their digest and the candidates it excluded with the reason.
harness memory manifest [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | no | latest |
Run (execution) identifier, latest or a unique prefix such as run_1a2b |
--path |
path | no | Project directory |
harness memory approve¶
Approve a proposed record. The approval is a new record that supersedes the proposal; approving a record that needs no approval or is already approved exits with code 5.
harness memory approve [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--memory |
str | yes | Memory record identifier | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--path |
path | no | Project directory |
harness memory invalidate¶
Invalidate a record without deleting it: it stops entering any context and the actor and the reason stay on record.
harness memory invalidate [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--memory |
str | yes | Memory record identifier | |
--reason |
str | yes | Why the record no longer applies | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--path |
path | no | Project directory |
harness recommendation list¶
List the retrospective recommendations of a run with the decision recorded for each.
harness recommendation list [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | no | latest |
Run (execution) identifier, latest or a unique prefix such as run_1a2b |
--path |
path | no | Project directory |
harness recommendation decide¶
Accept, edit or reject a retrospective recommendation. The decision is kept as retrospective memory: an accepted or edited recommendation enters the context of later runs, a rejected one stays as history. A second decision on the same recommendation exits with code 5; nothing is applied to rules, gates or configuration.
harness recommendation decide [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--recommendation |
str | yes | Recommendation identifier shown by retrospect | |
--decision |
ACCEPT | EDIT | REJECT |
yes | Decision on the recommendation | |
--rationale |
str | yes | Justification recorded with the decision | |
--statement |
str | no | Edited text of the recommendation; required with EDIT | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--path |
path | no | Project directory |
harness plugins list¶
List the built-in extensions and the external plugin protocol version.
harness plugins list [OPTIONS]
harness benchmark run¶
Run the synthetic microbenchmarks (hashing, transitions, gates, events, artifacts, process launch).
harness benchmark run [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--output |
path | no | Write to this file instead of standard output | |
--iterations |
int range | no | 1000 |
Iterations per in-process operation |
harness benchmark scenarios¶
Compare a direct patch-and-test path with the complete governed path on generated Python and Node.js projects.
harness benchmark scenarios [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--output |
path | no | Write to this file instead of standard output | |
--iterations |
int range | no | 3 |
Repetitions per scenario |
harness api serve¶
Serve the local API and web dashboard. Keep it bound to 127.0.0.1.
With the api section that harness init writes, every route requires Authorization: Bearer TOKEN. Your token comes from the variable in api.tokenEnv (HARNESS_API_TOKEN by default); when it is not set, a new token is generated and printed once on standard error. Without the section there is no authentication, as in 1.0.0.
harness api serve [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Project directory | |
--host |
str | no | 127.0.0.1 |
Bind address; keep the loopback default |
--port |
int range | no | 8765 |
TCP port |
harness artifact show¶
Print an artifact's content after verifying its digest, or its descriptor with --describe. Artifacts are stored redacted; a digest mismatch exits with 1.
harness artifact show [OPTIONS] {reference}
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
reference |
str | yes | ||
--describe |
flag | no | false | Print the descriptor (digest, size, media type, metadata) |
--path |
path | no | Project directory |
harness exceptions list¶
List the exceptions of the project (review.exceptions): who granted each, on which run and digest, its scope, alternative evidence and follow-up, when it expires and the runs whose gate relied on it. An expired exception no longer covers any finding.
harness exceptions list [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--status |
str | no | all |
all, active or expired |
--expiring-within |
int range | no | Only active exceptions expiring within N days | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) | |
--path |
path | no | Project directory |
harness rules health¶
Show how each rule and validator behaved across the runs of the project: how often it fired, blocked a gate, was excepted, fired on a ChangeSet that was later corrected, fired in a rejected run or in a run later linked to an outcome. Read-only; nothing is changed and no figure is per person.
harness rules health [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--since |
int range | no | Only runs created in the last N days | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) | |
--path |
path | no | Project directory |
harness outcome record¶
Link something that happened after a run (an incident, a revert, a hotfix, a regression)
to it. The outcome feeds harness rules health and the causal retrospective; nothing is
applied. An actor id of an agent, validator or the harness exits with 5.
harness outcome record [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--kind |
str | yes | INCIDENT, REVERT, HOTFIX, REGRESSION or OTHER | |
--summary |
str | yes | What happened | |
--reference |
str | no | Link or identifier of the incident, revert or fix | |
--observed-at |
str | no | ISO 8601 instant it happened (default: now) | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) | |
--path |
path | no | Project directory |
harness outcome list¶
List the outcomes linked to the runs of the project, oldest first.
harness outcome list [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | no | Only the outcomes of this run | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) | |
--path |
path | no | Project directory |
harness plan show¶
Show the decomposition PLANNING proposed for a run (planning.decomposition), its
digest, its status and the sub-tasks completed so far.
harness plan show [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--path |
path | no | Project directory |
harness plan decide¶
Approve or reject the proposed decomposition, bound to its digest. APPROVE runs the sub-tasks in order, each with its own verification and gate; REJECT keeps the task whole. A stale digest, a non-human actor or a decision other than APPROVE or REJECT exits 5. An APPROVE with --no-continue exits 0 once it is recorded, as gate decide does.
harness plan decide [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--decision |
APPROVE | REJECT | REQUEST_CHANGES | APPROVE_EXCEPTION |
yes | APPROVE or REJECT | |
--digest |
str | yes | Digest of the proposed plan shown by plan show | |
--rationale |
str | yes | Justification recorded | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--continue, --no-continue |
flag | no | --continue | Resume the run after recording the decision |
--path |
path | no | Project directory |
harness acceptance show¶
Show the acceptance tests proposed for a run (verification.acceptanceTests), their
digest, their status and, once approved, the frozen files and their digests.
harness acceptance show [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--path |
path | no | Project directory |
harness acceptance decide¶
Approve or reject the proposed acceptance tests, bound to their digest. APPROVE writes and freezes them, runs them once on the workspace before the change and resumes the run; every later VERIFICATION checks that they are unchanged and pass. A stale digest or a non-human actor exits 5.
harness acceptance decide [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--decision |
APPROVE | REJECT | REQUEST_CHANGES | APPROVE_EXCEPTION |
yes | APPROVE or REJECT | |
--digest |
str | yes | Digest shown by acceptance show | |
--rationale |
str | yes | Justification recorded | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--continue, --no-continue |
flag | no | --continue | Resume the run after recording the decision |
--path |
path | no | Project directory |
harness acceptance dispute¶
Decide a dispute of the frozen acceptance tests
(verification.acceptanceTests.disputes): a run whose VERIFICATION failed only on those
tests, after an implementation whose self-report says a test is wrong, waits for a person
(kind acceptance-dispute in harness inbox; harness acceptance show lists the disputed
tests and the reasons). UPHOLD keeps the tests: the run verifies again and goes on to its
correction cycles or fails, as without the dispute. REVISE removes the frozen files and
returns the run to SPECIFICATION, where new tests are proposed and wait for harness
acceptance decide; once approved and frozen the run verifies the same change again. A
stale digest or a non-human actor exits 5.
harness acceptance dispute [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--decision |
UPHOLD | REVISE |
yes | UPHOLD or REVISE | |
--digest |
str | yes | Digest of the dispute (harness inbox) | |
--rationale |
str | yes | Justification recorded | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--continue, --no-continue |
flag | no | --continue | Resume the run after recording the decision |
--path |
path | no | Project directory |
harness budget show¶
Show the usage of a run and of its task (reported tokens and cost, measured wall time of
the agent calls) against the budget limits, the limits a person raised and what remains.
harness budget show [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--path |
path | no | Project directory |
harness budget raise¶
Raise a budget limit of a run blocked with budget.exceeded; the raise is recorded on the
run's event chain with the person and the rationale, then harness run continue resumes the
run. A non-human actor, a lower limit or a missing rationale exits 5, with a hint that names
harness budget show and the command to retry.
harness budget raise [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--scope |
str | yes | call, task or run | |
--metric |
str | yes | costUsd, tokens or wallSeconds | |
--to |
float | yes | The new limit; it must be above the current | |
--rationale |
str | yes | Justification recorded | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--path |
path | no | Project directory |
harness routing calibrate¶
Report the cost per approved task of every routing decision recorded in the project
(agentRouting), by provider family, call kind, task size, model and effort, and suggest
the cheapest implement rung per size among groups with at least two approved runs. Nothing
is applied: a person edits agentRouting.tables.
harness routing calibrate [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Project directory |
harness agent-contract schema¶
Print the JSON Schema of the request contract (what a parent sends an agent call), of the response contract (what the parent receives) or of a script contract.
harness agent-contract schema [OPTIONS] {contract}
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
contract |
str | yes |
harness agent-contract validate¶
Validate a JSON file against a contract; output is the JSON an agent prints, checked
against the limits of its call kind. Exit 0 when it keeps the contract, 6 when it does not
(the violation is printed).
harness agent-contract validate [OPTIONS] {document} {file}
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
document |
str | yes | ||
file |
path | yes | ||
--kind |
str | no | Call kind whose limits output is checked against |
harness agent-contract scripts¶
List the scripts and commands agents may call as black boxes, or show the contract (invocation, inputs, outputs, errors) of one.
harness agent-contract scripts [OPTIONS] [script]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
script |
str | no | ||
--path |
path | no | Project directory |
harness agent-contract calls¶
Show the agent calls of a run, the iterations each agent used against its cap and, with --kind (and --iteration), exactly what was sent, what the parent received, and whether the stored request matches its digest and the context the contract allowed.
harness agent-contract calls [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--kind |
str | no | Show one call kind | |
--iteration |
int | no | Show one iteration | |
--path |
path | no | Project directory |
harness pr publish¶
Post the decision brief of a run on a pull or merge request (one comment per run, updated when published again) and attach the run's findings: SARIF to GitHub code scanning, a Code Insights report on Bitbucket; GitLab and Azure DevOps read the report from CI artifacts. GitHub is the default; another forge is detected from the origin remote or set with --forge or delivery.forge. Information only: nothing is decided on the forge.
harness pr publish [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--pr |
int range | yes | Pull request number | |
--run |
str | no | latest |
Run (execution) identifier, latest or a unique prefix such as run_1a2b |
--repository |
str | no | owner/name (default: delivery.publisher or the origin remote) | |
--transport |
str | no | gh (the GitHub CLI) or api (HTTPS with the token in delivery.publisher.tokenEnv, GITHUB_TOKEN by default) | |
--sarif, --no-sarif |
flag | no | Upload the run's findings to code scanning | |
--commit |
str | no | Commit the SARIF report belongs to (default: the PR head) | |
--forge |
str | no | github, gitlab, bitbucket, azure-devops or gitea (default: delivery.forge, else detected from the origin remote) | |
--path |
path | no | Project directory |
harness pr create¶
Open a pull or merge request from the closure branch of a run (push the branch first), with the repository's pull request template and the decision brief as its description and the configured labels. The creation is recorded as a delivery.pull-request.created event. Nothing is approved on the forge: the approval is the run's digest-bound decision.
harness pr create [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | no | latest |
Run (execution) identifier, latest or a unique prefix such as run_1a2b |
--base |
str | no | Target branch (default: delivery.forge.baseBranch) | |
--head |
str | no | Source branch (default: the closure branch of the run) | |
--title |
str | no | Title (default: the task title) | |
--label |
str | no | Label, added to delivery.forge.labels (repeatable) | |
--draft, --ready |
flag | no | Open it as a draft (default: delivery.forge.draft) | |
--forge |
str | no | github, gitlab, bitbucket, azure-devops or gitea | |
--repository |
str | no | Repository path on the forge (default: the origin remote) | |
--transport |
str | no | cli (gh or glab) or api (HTTPS, token from the environment) | |
--path |
path | no | Project directory |
harness pr status¶
Set the commit status governed-harness from a run: success once it closed approved, pending while it waits for a human decision, failure otherwise.
harness pr status [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--commit |
str | yes | Commit whose status is set | |
--run |
str | no | latest |
Run (execution) identifier, latest or a unique prefix such as run_1a2b |
--target-url |
str | no | Link shown with the status (for example the CI job) | |
--forge |
str | no | github, gitlab, bitbucket, azure-devops or gitea | |
--repository |
str | no | Repository path on the forge (default: the origin remote) | |
--transport |
str | no | cli (gh or glab) or api (HTTPS, token from the environment) | |
--path |
path | no | Project directory |
harness pr forge¶
Show the forge the workspace resolves to (delivery.forge or the origin remote), its API URL, transport and the environment variable its token is read from. Calls nothing.
harness pr forge [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Project directory |
harness verification show¶
Show the verification plan of a run (the rung each criterion requires, the rungs this environment reaches and why), its preflight (READY, PARTIAL or UNAVAILABLE), the certification of its ChangeSet, the deferred items and the manual checklist.
harness verification show [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | no | latest |
Run (execution) identifier, latest or a unique prefix such as run_1a2b |
--path |
path | no | Project directory |
harness verification decide¶
Decide on a run whose preflight is UNAVAILABLE: continue it uncertified for what this environment cannot verify (those criteria end WAIVED, never certified; the unavailable probes are not run). Recorded on the run with the person and the rationale. A run that does not wait on such a preflight, or a non-human actor, exits 5.
harness verification decide [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--continue-uncertified |
flag | no | false | Continue without the rungs the preflight found unreachable (required) |
--rationale |
str | yes | Justification recorded | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--continue, --no-continue |
flag | no | --continue | Resume the run after recording the decision |
--path |
path | no | Project directory |
harness standards show¶
Show the language standards packs: the detected and effective packs (repository overrides applied), their tools and the validators added for the tools the repository configures; with --lang every card of one pack; with --file the cards selected for those files. Works without a project configuration. Reads only.
harness standards show [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--lang |
str | no | One pack (python, typescript, java, ...) with all its cards | |
--file |
str | no | A workspace path: show the cards an implement call and the review checklist would get for it (repeatable) | |
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness architecture show¶
Show the architecture of the project: the configured section, whether the project is new or existing, the cached survey or the ADR, the layer rules in force with their forbidden imports, and the source layout the survey cache is keyed by.
harness architecture show [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness architecture decide¶
Decide the architecture, bound to the digest of the proposal: approve or reject the layer rules a survey inferred (existing project), or choose one of the options of a new project, which is recorded as an ADR; under architecture.catalogue: experts --style chooses any style of the catalogue instead. The approved rules are enforced as forbidden dependencies in VERIFICATION. A stale digest or a non-human actor exits 5.
harness architecture decide [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | yes | Run (execution) identifier, latest or a unique prefix such as run_1a2b |
|
--digest |
str | yes | Digest shown by the blocked phase | |
--rationale |
str | yes | Justification recorded | |
--decision |
APPROVE | REJECT | REQUEST_CHANGES | APPROVE_EXCEPTION |
no | APPROVE or REJECT the layer rules a survey inferred | |
--option |
str | no | The architecture option chosen for a new project | |
--style |
str | no | A style of the catalogue chosen for a new project (architecture.catalogue: experts) | |
--actor |
str | no | Identifier of the person acting (recorded, not authenticated). Defaults to the Git user under governance.deciderIdentity: git, otherwise human.local. Ids of agents, validators and the harness (agent., validator., harness.*) are refused with exit code 5. | |
--continue, --no-continue |
flag | no | --continue | Resume the run after recording the decision |
--path |
path | no | Project directory |
harness architecture refresh¶
Mark the cached architecture survey stale: the next run surveys the project again (one call). Approved rules stay in force until a new survey is decided.
harness architecture refresh [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Project directory |
harness project show¶
Show what the harness detects about the project, deterministically and without an agent call: new or existing (and why), profiles, standards packs, testing strategy, architecture status, project setup answers and forge.
harness project show [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness mcp serve¶
Serve the harness to an agent session over stdio (Model Context Protocol, JSON-RPC 2.0, one message per line). Tools: project, status, inbox, task create, questions and clarify (the person's answers, marked as relayed), run start (provider session by default) and continue, check, review and standards. No tool decides for a person: gate, acceptance, plan and architecture decisions stay in the terminal. Register it, for example, with claude mcp add harness -- harness mcp serve.
harness mcp serve [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Project directory |
harness review¶
Show the decision brief of a run: what was asked, what changed, the risks with file and line, what was verified on which ChangeSet digest and what was not, active exceptions, retries and corrections, what changed since the last decision and the exact decide command. It only reads the record. The subcommands manage the review panel (#57).
harness review [OPTIONS] COMMAND [ARGS]...
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--run |
str | no | latest |
Run (execution) identifier, latest or a unique prefix such as run_1a2b |
--diff |
flag | no | false | Include the ChangeSet diff (redacted) |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) | |
--path |
path | no | Project directory |
harness review verify¶
Check the review evidence of a commit (refs/harness/review/pass/SHA or pass-warn) without calling any model: the report is bound to the commit, its digest is intact and its diff is the diff between its base and the commit. Exit code 6 when it does not verify.
harness review verify [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--sha |
str | no | HEAD |
The commit whose review evidence to check |
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness review variance¶
Run the same review several times without cache and report its variance: verdict stability, how often each finding appears and the mean pairwise agreement (Jaccard). Every run calls the reviewers again.
harness review variance [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--runs |
int range | no | 3 |
Identical reviews to run |
--mode |
str | no | manual |
manual or staged |
--base |
str | no | Base branch or commit | |
--provider |
str | no | Provider of the reviewers | |
--model |
str | no | Force one model for every reviewer | |
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness review rules show¶
Show the effective review rule catalog: the rules of the three layers (built-in, language packs, project) after precedence and supersedes, the inactive rules and why, the reviewers and the ones whose rules block drifted. Reads only.
harness review rules show [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness review rules sync¶
Write the generated rules block of every project reviewer (.harness/review/agents) from the catalog, between its BEGIN and END markers; the only writer of that block. With --check nothing is written and a drift exits with 6.
harness review rules sync [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--check |
flag | no | false | Only report project reviewers whose rules block drifted (exit 6) |
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |
harness review hook install¶
Install a pre-push hook that runs harness review-code --mode hook: a FAIL or UNKNOWN verdict, or a base that cannot be fetched, stops the push.
harness review hook install [OPTIONS]
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--force |
flag | no | false | Replace a pre-push hook the harness did not write |
--path |
path | no | Project directory | |
--json, --no-json |
flag | no | Print JSON, or readable text with --no-json (default: JSON unless standard output is a terminal) |