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] [--recompute-step step-id] [--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. This retains its existing behavior for implicit single-step pipelines; explicit multi-step pipelines reject it rather than inferring dependency closure.
• --resume: request checkpoint reuse for this invocation. Checkpoint recording must be enabled in configuration. See Operations for prerequisites and reuse behavior.
• --recompute-step step-id: with --resume and checkpoint recording enabled, force the named ordered step and every transitive dependent lane to execute. Compatible required predecessors and unrelated lanes remain reusable. The value must identify an explicit step; it cannot be combined with --only.
• --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 external file bindings resolved against selected chunk, extractor, merger, and normalizer targets before the run starts. Generated artifact bindings are configured in ordered steps and cannot be introduced by a CLI path flag. 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 maintained NPC-grounded workflow, use the explicit ordered pipeline. The first step produces the normalized NPC artifact; the second step receives it in memory and fans it out to spell extraction, combat extraction, and combat normalization:

go run ./cmd/notarius run dnd-npc-grounded \
  --config examples/dnd-npc-grounded.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --output-dir ./npc-grounded-output

The generated NPC content remains contextual grounding, not spell or combat evidence. It is represented in manifests and debug summaries by bounded identity and producer provenance, not by payload content or a filesystem path.

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

To selectively rerun one ordered step and its dependent lanes, use the step ID from the configuration. The selected step and dependents are reported as forced_recompute; reusable predecessors are reported as reused:

go run ./cmd/notarius run dnd-npc-grounded \
  --config examples/dnd-npc-grounded.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --resume --recompute-step grounded-events

Checkpoint decisions use these categories: reused, executed, forced_recompute, and dependency_invalidated. The reason code and bounded detail identify the decision without exposing reference content, local paths, or secrets. --recompute-step requires checkpoint recording and --resume; unknown step IDs, empty values, and combinations with --only are rejected.

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.