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	Override the generated prompt session identifier with a non-empty value for 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.

Every run uses one effective prompt session. Without --session-id, Notarius generates a stable notarius:v1: identifier from the trimmed resolved input module key and the input file's exact raw bytes. The same module and bytes therefore produce the same identifier, regardless of pipeline, references, profile, retries, or run settings. An explicit non-empty value replaces that default. Session identifiers are visible to providers; they are non-secret correlation identifiers, not credential storage. See Operations for privacy and workflow guidance.

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.