notarius/docs/cli.md

CLI Reference

This is the canonical reference for the implemented Notarius command-line interface. For the shortest successful run, see the README. Configuration fields, discovery rules, and selectable module keys are defined in Configuration; runtime state and recovery procedures are defined in Operations.

Command Summary

notarius help
notarius run <pipeline-id> --input path/to/source.json [--json] [flags]
notarius config validate [--config path/to/config.yml] [--pipeline pipeline-id] [--only lane-a,lane-b]
notarius pipelines list [--config path/to/config.yml] [--json]

Running Notarius without arguments, or with help, --help, or -h, writes the command summary to standard output and exits with status 0.

run

notarius run <pipeline-id> --input path/to/source.json [--json] [flags]

The run command executes the named pipeline for one input file. The pipeline ID and --input are required.

Flag	Meaning
--config path	Use this configuration file. When omitted, configuration discovery applies; see Configuration.
--input path	Source input file to process. Required.
--output-dir path	Override the configured output root for this run.
--json	Write the successful run-result receipt as JSON to standard output.
--chunk_cache auto|bypass|refresh	Override chunk-plan cache handling for this run.
--resume	Reuse compatible recorded checkpoints when checkpoint recording is enabled.
--recompute-step step-id	With --resume, recompute the selected ordered step and its dependent lanes. It cannot be combined with --only.
--debug	Retain a debug bundle for this run.
--debug-dir path	Override the debug-bundle root. Requires --debug.
--only lane-a,lane-b	Run only the selected comma-separated artifact lanes when that selection is valid for the configured pipeline.
--llm-profile id	Highest-precedence configured profile for selected LLM-backed bindings and validators; it replaces binding and pipeline defaults.
--session-id id	Supply a non-empty prompt session identifier to LLM-backed module calls.
--reasoning-effort value	Replace the selected PromptKit profile's reasoning effort for every LLM-backed call in this run. The value must be non-empty and the flag may be specified only once.
--clear-reasoning-effort	Clear reasoning effort inherited from the selected PromptKit profile for every LLM-backed call in this run.
--reference selector=path	Add or replace a file reference binding. Repeatable.
--without-reference selector	Remove a configured optional reference binding. Repeatable.

--chunk_cache accepts only auto, bypass, or refresh. --debug-dir, --output-dir, --session-id, and --reasoning-effort, and --recompute-step reject explicit empty values. --reasoning-effort and --clear-reasoning-effort are mutually exclusive. When neither is present, reasoning effort comes from the selected PromptKit profile. These controls apply to the shared run client, including retries and LLM-backed validators, and do not modify configuration or profile files. Persistent reasoning settings remain a PromptKit profile concern. --recompute-step requires --resume; checkpoint requirements and reuse behavior are documented in Operations.

Reference selectors

Use --reference only for a reference slot declared by the selected configured target. The accepted selector forms are:

Form	Target
slot=path	The unique selected target that declares slot.
chunk.slot=path	The chunker.
merge.slot=path	The unique selected merger that declares slot.
lane.slot=path	The unique extractor, merger, or normalizer in lane that declares slot.
lane.extract.slot=path	The extractor in lane.
lane.merge.slot=path	The merger in lane.
lane.normalize.slot=path	The normalizer in lane.

--without-reference uses the same selector forms without =path. Slot names, requiredness, and configured bindings are part of the configuration contract.

Run output

Without --json, standard output contains the completed pipeline ID, counts of normalized and rejected outputs, and the output directory. A debug-enabled run also prints its debug-bundle path to standard output. A successful run with warnings reports the warning count to standard error. The published JSON bundle is defined by the JSON output contract.

With --json, successful standard output is exactly one notarius.run-result.v1 JSON document followed by a newline, with no human-oriented status or debug-path line. Its fields and compatibility policy are defined by the run-result contract. A caller must check for exit status 0 before decoding this output; a failed write can leave incomplete standard-output bytes that are not a result document.

Example:

OPENROUTER_API_KEY=your-api-key \
  go run ./cmd/notarius run dnd-session \
    --config examples/dnd-minimal.config.yml \
    --input examples/seriatim-minimal-transcript.json

config validate

notarius config validate [--config path/to/config.yml] [--pipeline pipeline-id] [--only lane-a,lane-b]

This command loads and validates a configuration. With --pipeline, it also resolves that pipeline against the production module catalog. --only selects lanes during that resolution and requires --pipeline.

Success is written to standard output as either config "" is valid or config "" is valid for pipeline "".

Examples:

go run ./cmd/notarius config validate \
  --config examples/dnd-minimal.config.yml \
  --pipeline dnd-session

OPENROUTER_API_KEY=validation-placeholder \
  go run ./cmd/notarius config validate \
    --config examples/dnd-complete.config.yml \
    --pipeline dnd-session

The placeholder in the second command is sufficient only for offline validation; it cannot run a provider-backed pipeline.

pipelines list

notarius pipelines list [--config path/to/config.yml] [--json]

This command lists configured pipeline IDs in sorted order. By default, it writes one ID per line to standard output. --json writes an object shaped as {"pipelines":[...]} instead.

go run ./cmd/notarius pipelines list \
  --config examples/dnd-minimal.config.yml

Output Streams And Exit Statuses

Successful commands write their primary result to standard output. Warnings and errors are written to standard error.

For run --json, warnings remain on standard error and standard output is a machine-readable success result only. Syntax and runtime diagnostics remain on standard error. Parse the result only after the process exits with status 0.

Status	Meaning
0	The command completed successfully, including root help.
1	Command syntax was valid but configuration loading or validation, pipeline resolution or execution, provider use, output, or requested debug handling failed.
2	The command or flag syntax was invalid, including unknown commands, missing required arguments, invalid flag values, or invalid flag combinations.

The root help spellings are the supported help path. Invoking --help on run, config validate, or pipelines list is handled by the flag parser as a usage error: it writes an error to standard error and exits with status 2.