notarius/docs/cli.md

CLI Reference

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

Quick Run

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

The maintained example uses prompt defaults and Scriptorium's built-in mistral-small-3 profile, which reads OPENROUTER_API_KEY. To use another endpoint or model, configure a Scriptorium profile source and select its profile ID in config or with --llm-profile.

Commands

notarius help
notarius run <pipeline-id> --input path/to/source.json [--config path/to/config.yml] [--only lane-a,lane-b] [--resume] [--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 checks NOTARIUS_CONFIG, then /usr/local/etc/notarius/config.yml.
• --only lane-a,lane-b: run only the named artifact lanes. Values are comma-separated and must be non-empty.
• --resume: reuse valid workspace checkpoints for this invocation. Requires an effective workspace directory and workspace.resume.enabled: true.
• --output-dir path: output root. The run writes to <path>/<run-id>/. Defaults to ./notarius-output.
• --diagnostics-dir path: diagnostics work directory override for this invocation. It does not change the workspace directory.
• --llm-profile id: override every effective LLM-capable pipeline module binding to use one Scriptorium profile ID. Validator-specific profiles are not overridden. Configured LLM-backed validators with explicit profiles are validated against the configured Scriptorium profile source.
• --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. 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. Bound reference files are read before pipeline work starts, validated as UTF-8 text, and recorded as provenance for the target that declares the slot. Runtime reference content is passed to the chunker, extractor, merger, or normalizer target that declares the slot. Notarius infers reference media types from file extensions for provenance and for optional slot checks. Reference content is not written to diagnostics, logs, errors, or manifests.

Reference binding precedence is:

1. pipeline-level config references;
2. target-local config references, including legacy lane-level extractor references;
3. --reference run flags;
4. --without-reference run flags.

--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

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

Use --resume to reuse valid checkpoints from a previous compatible invocation:

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

Plain run does not skip completed work. It executes the pipeline normally and refreshes checkpoints when checkpointing is enabled. --resume verifies each checkpoint before reuse and executes any missing, corrupt, or incompatible step normally.

For durable output, diagnostics, retention, and failure inspection, see Operations.

config validate

notarius config validate loads and validates configuration.

Flags:

• --config path: config file path. If omitted, discovery uses NOTARIUS_CONFIG, then /usr/local/etc/notarius/config.yml.
• --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, discovery uses NOTARIUS_CONFIG, then /usr/local/etc/notarius/config.yml.
• --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 diagnostics failed.
• 2: command syntax was invalid, a command was unknown, a required argument was missing, or a flag value was malformed.

Implemented Production Pipeline Modules

The production CLI currently registers these module keys:

• input: seriatim
• chunk: generic, dnd/scenes
• extract: dnd/spells
• merge: appendorder
• normalize: noop
• output: json

Implemented Production Validators

The production CLI currently registers these validator keys:

• generic/always_accept
• generic/always_reject
• generic/valid_json
• generic/valid_json_schema
• extract/dnd/spells/shape
• extract/dnd/spells/source_refs
• extract/dnd/spells/source_relatedness

The production default chain for the dnd/spells extractor is:

1. generic/valid_json
2. generic/valid_json_schema
3. extract/dnd/spells/shape
4. extract/dnd/spells/source_refs
5. extract/dnd/spells/source_relatedness

Validator chain overrides are configured on chunk, lane extract, lane merge, and lane normalize bindings. Omitted overrides use production defaults, validators: [] disables validation for that binding, and non-empty lists replace the default chain in configured order. Validator keys are resolved against the registered validator catalog.

For YAML structure, Scriptorium profile sources, environment overrides, and module binding syntax, see Configuration.