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] [--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.
• --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.
• --llm-profile id: override every effective LLM-capable module binding to use one Scriptorium profile ID.
• --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, 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, 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, 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;
• lane.slot=path: valid when exactly one selected extractor or normalizer in that lane declares slot;
• lane.extract.slot=path: target a lane extractor;
• 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 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.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

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

The production CLI does not currently register validator modules.

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