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 [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 [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.
--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	Override effective LLM-capable module bindings with one configured profile.
--session-id id	Supply a non-empty prompt session identifier to LLM-backed module calls.
--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 --recompute-step reject explicit empty values. --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

On success, 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 envelope is defined by the JSON output contract.

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.

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.

5.9 KiB Raw Blame History