CLI reference | MetaharnessCLI reference in the source-owned Metaharness documentation.Metaharnessreferencemetaharnessreferenceevaluatordeveloperresearcherreference

CLI reference

ReferenceMetaharness

ForEvaluator · Developer · Researcher

Source & revision

metaharness/website/docs/reference/cli.mdx · a5203290ba6f

metaharness <VERB> [OPTIONS]

Six verbs. Three of them need no model, no network and no credential.

Verb	What it does
run <KIND>	Run a harness session: events as JSON lines on stdout, commands as JSON lines on stdin.
capabilities <KIND>	What an adapter says it can do: declared tiers, pinned versions, operation rendering.
conformance <KIND>	The free conformance vectors: no model, no network, no credential.
doctor <KIND>	The installed vendor version against the adapter's pin.
project --events <FILE>	Project an event stream into trace-ir/1. Refuses with exit 2 — see Status.
audit --transcript <FILE>	Judge a transcript offline. Refuses with exit 2.

<KIND> is claude, codex or b10x. The first two are vendors metaharness drives; the third is the beyond10x loop, which it observes — see the b10x adapter.

metaharness run

The run itself

Flag	Default	Meaning
<KIND>	—	Which harness.
-p, --prompt <TEXT>	—	The prompt to start with.
--model <NAME>	—	The model to ask for. Passed through to the vendor, which resolves it.
--max-turns <N>	—	A ceiling on turns.
--cwd <DIR>	scratch	An operator-named working directory for the child, which it can write to. Trades two hermetic rows for real work — see below.

Hermeticity

Flag	Default	Meaning
--hermetic [off|on|strict]	off; bare --hermetic means on	See the hermetic contract.
--credentials <SOURCE>	operator-login	operator-login, api-key, loopback, or none.
--plugin-dir <DIR>	(none)	Plugin directories to load, and only these. Repeatable. Copied into the scratch tree and digested before the child starts; on b10x, handed to the loop as its own --plugin-dir.
--strict-version	off	Refuse before the run when the installed vendor version is outside the adapter's pin, instead of warning.

--credentials none means the run is expected to fail at the first request — and that is sometimes exactly what a test wants.

Model, effort and actor

Flag	Meaning
--model-endpoint <BASE_URL>	A model gateway, as its root URL (no /v1); each harness reaches its own dialect under it.
--model-wire <WIRE>	Which API the harness speaks under that root — only b10x has a choice: openai-responses or anthropic-messages.
--subscription-token-file <FILE>, --subscription-token-env <NAME>, --subscription-token-pointer <POINTER>	A subscription token for a route that takes one instead of an API key; the pointer selects a field inside a JSON source. Not interchangeable with --credentials api-key.
--effort <LEVEL>	Reasoning effort in the vendor's vocabulary, passed through and validated by the vendor.
--actor <ACTOR>	Who the run's store writes are made as, carried to the child as AEP_ACTOR — declared, never inherited.
--retain-dir <DIR>	Copy the raw vendor wire out of the scratch root before it is deleted.

--credentials api-key is a declaration: without it, ANTHROPIC_API_KEY is not in the child environment at all.

--credentials loopback puts metaharness in front of the vendor: the child holds a per-run placeholder and no credential file, and one custody attaches the real token on the way out. On Claude Code the child is pointed at the proxy by ANTHROPIC_BASE_URL; on codex by a [model_providers.metaharness_loopback] entry in the scratch CODEX_HOME. A ChatGPT-plan codex login is refused by name — see the codex adapter.

Control

Flag	Default	Meaning
--frame <FILE>	—	A sealed metaharness.frame/1 document. See frames.
--decisions <MODE>	frame	frame (the adapter decides from the admitted set) or ask (the embedder decides; one round trip per call).
--tool-surface <SURFACE>	native	native, or owned — which this build refuses.

The frame is a path, not a parsed value, on purpose: resolving it is the library's job, and parsing it in the binary would put protocol logic in the CLI.

Audit

Flag	Meaning
--audit	Judge the run: the built-in hermetic floor always, the external auditor when --spec is given.
--spec <FILE>	The expectation document the external auditor is pointed at.
--auditor <PREFIX>	The external auditor, as an argv prefix.
-- <AUDITOR_ARGS>…	Arguments passed through to the auditor after everything metaharness adds.

:::danger A --spec with no --auditor is a refusal, not a skip A specification nobody checked reads exactly like a specification that passed. :::

--auditor takes an argv prefix, so a single-word program name is a degenerate prefix and a two-word subcommand is not a special case.

After decision census:, --audit prints what the machine would not admit, in one of three shapes because they are three facts: withheld: <tool> (<reason>); …, withheld: none declared, or withheld: not stated by the harness. The census cannot say it — a tool that was never admitted was never refused, so denied=0 reads the same on a run that got everything.

The b10x arm

These reach the beyond10x loop and are refused by name on claude and codex: a vendor arm's scope travels sealed in Frame.subjects, and a flag would be a second, unsealed copy of it.

Flag	Meaning
--hooks <FILE>	The operator's own programs, consulted by the loop at each call — its only content-level refusal. Named, never discovered.
--driver <PATH>	A program the confined run must be able to start: staged, mounted read-only, added to the loop's allow-list. Not the same question as --allow-program, which says what a run may name.
--allow-program <PROGRAM>	A program the loop's run tool may start. Repeatable; empty publishes no run.
--substrate <SOCKET>, --substrate-embedded	Confinement for the loop: a substrate daemon, or its driver held in-process. Never both.
--cgroup-root <DIR>	A delegated cgroup subtree; without one no run entry is published.
--toolchain <NAME>	A build toolchain admitted read-only inside the confined workspace.
--prices <FILE>	A rate card, so the record states what the run cost; the loop has no vendor catalogue behind it.
--write-scope <GLOB=SCOPE>	<glob>=allowed|partial-only|denied, ordered, first match wins. The operation is refused, never the run.
--scope-announce stated|silent	Whether the scope is also stated in the instruction; silent is an experiment control.
--context <FILE>	A file the run is given before it starts; paid on every turn of a stateless loop. A missing file refuses the run.

What the launch emits, and how the seam reads the record back, is on the b10x adapter.

--cwd: the declaration that trades two rows for real work

The child runs in this tree, and can write to it. So:

• H7 ("the working directory is ours") and H11 ("no memory file outside the copied tree") stop being impositions and are attested unavailable, naming this directory.
• The vendor sandbox is widened to that tree so the work can actually happen — on codex the scratch config carries sandbox_mode = "workspace-write", which permits editing files in the cwd. The H7 attestation row says so in words: a reader sees that the run could write to the operator's tree without diffing a scratch config that no longer exists.
• --hermetic strict therefore refuses such a run.
• Plain --hermetic reports it honestly.
• --add-dir stays denied either way, and no writable_roots widens the grant past this tree.

The embedder that wants a governed run over a real repository accepts exactly that trade. A scratch-cwd run is unchanged: the child writes nothing, anywhere.

:::note Why the grant is part of the trade Until 2026-08-23 it was not, and the trade bought nothing: a paid codex run with --cwd got a real repository it could only read, and the vendor's own stream said "the workspace is read-only, so the planning-store patch was rejected." Design amendment a6.1. :::

metaharness capabilities

Flag	Meaning
--render	Print the neutral-operation → vendor-tool table instead of the whole descriptor.

A rendering that only exists inside a run cannot be asserted on before one — which is why it is published here.

metaharness audit and metaharness project

Flag	Verb	Meaning
--events <FILE>	both	The event stream. Required for project, optional for audit.
--to <FORM>	project	The target form. Default trace-ir.
--transcript <FILE>	audit	The raw vendor transcript to judge.
--spec <FILE>	audit	The expectation document.
--auditor <PREFIX>	audit	The external auditor, as an argv prefix.

Both currently refuse with exit 2, naming what they wait for.

Exit codes

Code	Meaning
0	Completed; every gating hermetic row is ok.
1	A gating row is gap.
2	Refused — a verb or option that is not built.
3	A gating row is unk. Not a softer gap.