notarius/docs/cli.md

CLI Reference

This is the canonical reference for the implemented Notarius command-line interface.

For the minimal end-to-end invocation, see the README.

Commands

notarius help
notarius run <pipeline-id> --input path/to/source.json [--config path/to/config.yml] [--only lane-a,lane-b] [--chunk_cache auto|bypass|refresh] [--output-dir path] [--resume] [--debug [--debug-dir path]] [--llm-profile id] [--session-id id] [--reference selector=path] [--without-reference selector]
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 with no arguments, notarius help, notarius --help, or notarius -h prints usage and exits successfully.

run

notarius run <pipeline-id> executes a configured pipeline against one input file.

Flags:

• --input path: required source input file.
• --config path: config file path. If omitted, Notarius uses the discovery rules in Configuration.
• --only lane-a,lane-b: run only the named artifact lanes. Values are comma-separated and must be non-empty.
• --resume: request checkpoint reuse for this invocation. Checkpoint recording must be enabled in configuration. See Operations for prerequisites and reuse behavior.
• --chunk_cache auto|bypass|refresh: select chunk-plan reuse for this invocation. auto reuses a valid plan by canonical source digest, bypass performs no plan-cache I/O, and refresh regenerates and replaces a valid plan only after chunk validation succeeds. See Configuration for the persistent setting, precedence, and cache-root selection.
• --output-dir path: output root. Defaults to ./notarius-output.
• --debug: allocate and retain one debug bundle for this invocation.
• --debug-dir path: debug-bundle root override. This flag requires --debug.
• --llm-profile id: override every effective LLM-capable pipeline module binding with one Scriptorium profile ID. Validator-specific profiles are not overridden.
• --session-id id: pass a stable prompt session identifier through LLM-backed module calls.
• --reference selector=path: bind a reference path to a chunk, extractor, merger, or normalizer reference slot. Repeatable.
• --without-reference selector: remove a configured optional reference binding. Repeatable. It accepts the same selector forms as --reference, without =path.

On success, the command prints the completed pipeline ID, normalized output and rejected output counts, and the output directory. A debug-enabled run also prints debug=<bundle-path>. If the run completes with warnings, the warning count is printed to stderr.

Reference flags are resolved against selected chunk, extractor, merger, and normalizer targets before the run starts. Flat slot names are accepted only when exactly one selected target declares that slot. For configured reference bindings, precedence, path resolution, and validation, see Configuration.

--reference binds or replaces one slot for one selected target. Selectors are:

• slot=path: valid when exactly one selected target declares slot;
• chunk.slot=path: target the chunker;
• merge.slot=path: valid when exactly one selected merger declares slot;
• lane.slot=path: valid when exactly one selected extractor, merger, or normalizer in that lane declares slot;
• lane.extract.slot=path: target a lane extractor;
• lane.merge.slot=path: target a lane merger;
• lane.normalize.slot=path: target a lane normalizer.

Use slot=path when the selected targets declare the slot unambiguously:

go run ./cmd/notarius run dnd-session \
  --config examples/dnd-spells.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --reference roster=./campaign-roster.txt

Use an explicit selector when multiple selected targets declare the same slot or when you want to target a specific target:

go run ./cmd/notarius run dnd-session \
  --config examples/dnd-spells.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --reference spells.extract.glossary=./campaign-glossary.txt

For the operator-driven NPC-to-spell workflow, bind the normalized NPC lane payload from the completed NPC run to the spell extractor:

go run ./cmd/notarius run dnd-spells \
  --config examples/dnd-npc-spell-sequential.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --reference spells.extract.npcs=./npc-run/lanes/npcs.json

For the independent NPC-to-combat workflow, bind the same completed NPC lane to both combat stages explicitly:

go run ./cmd/notarius run dnd-combat \
  --config examples/dnd-npc-combat-sequential.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --reference combat.extract.npcs=./npc-run/lanes/npcs.json \
  --reference combat.normalize.npcs=./npc-run/lanes/npcs.json

The two selectors are independent stage-local bindings. Binding extraction does not implicitly bind normalization, and Notarius does not discover or schedule the preceding NPC run.

The same grammar can target chunk, merge, and normalize slots when the configured modules declare them:

go run ./cmd/notarius run dnd-session \
  --config path/to/config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --reference chunk.scene_guide=./campaign-scenes.txt \
  --reference spells.merge.merge_notes=./merge-notes.txt \
  --reference spells.normalize.normalization_notes=./normalization-notes.txt

Use --without-reference to remove a configured optional binding for a run:

go run ./cmd/notarius run dnd-session \
  --config examples/dnd-spells.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --without-reference glossary

Use --session-id when an external orchestrator needs all prompt calls from one run to share an identifier:

go run ./cmd/notarius run dnd-session \
  --config examples/dnd-spells.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --session-id campaign-17-session-04

When cache.checkpoints.enabled is true, runs record checkpoints whether or not --resume is present. Add the resume flag to load and reuse compatible recorded work; using it while checkpoint recording is disabled is an error:

go run ./cmd/notarius run dnd-session \
  --config examples/dnd-spells.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --resume

Use --debug to retain the redacted summary and trace bundle for one run. The bundle is allocated before pipeline resolution; once allocated, its path is also printed to stderr if the command fails. Debug-write failures cause exit code 1.

go run ./cmd/notarius run dnd-session \
  --config examples/dnd-spells.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --debug --debug-dir ./notarius-debug

Use refresh when intentionally replacing the cached plan for the same source:

go run ./cmd/notarius run dnd-session \
  --config examples/dnd-spells.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --chunk_cache refresh

Use bypass for a one-off run that must not inspect or create plan-cache state:

go run ./cmd/notarius run dnd-session \
  --config examples/dnd-spells.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --chunk_cache bypass

--diagnostics-dir has been removed. For checkpoint behavior, durable output, debug-bundle lifecycle, and failure inspection, see Operations.

config validate

notarius config validate loads and validates configuration.

Flags:

• --config path: config file path. If omitted, Notarius uses the discovery rules in Configuration.
• --pipeline pipeline-id: additionally resolve one configured pipeline against the production module catalog.
• --only lane-a,lane-b: validate resolution for selected artifact lanes. This flag requires --pipeline.

Examples:

go run ./cmd/notarius config validate \
  --config examples/dnd-spells.config.yml

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

pipelines list

notarius pipelines list prints configured pipeline IDs in sorted order.

Flags:

• --config path: config file path. If omitted, Notarius uses the discovery rules in Configuration.
• --json: print {"pipelines":[...]} instead of one ID per line.

Examples:

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

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

Exit Codes

• 0: command succeeded.
• 1: command syntax was valid, but loading config, resolving modules, running the pipeline, calling the provider, writing output, or writing a requested debug bundle failed.
• 2: command syntax was invalid, a command was unknown, a required argument was missing, or a flag value was malformed.

For YAML structure, defaults, Scriptorium profile sources, environment overrides, and selectable module and validator keys, see Configuration.