notarius/docs/cli.md

CLI Reference

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

Quick Run

NOTARIUS_LLM_DEFAULT_BASE_URL=http://127.0.0.1:8080/v1 \
NOTARIUS_LLM_DEFAULT_MODEL=your-model \
go run ./cmd/notarius run dnd-session \
  --config examples/dnd-spells.config.yml \
  --input examples/seriatim-minimal-transcript.json

Set NOTARIUS_LLM_DEFAULT_API_KEY if the OpenAI-compatible provider requires a bearer token.

Commands

notarius help
notarius run <pipeline-id> --input path/to/source.json [--config path/to/config.yml] [--only lane-a,lane-b] [--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 module binding to use one LLM profile.
• --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, approved and rejected artifact 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

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

The current run command requires the resolved pipeline to use exactly one distinct LLM profile after defaults and overrides are applied.

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, defaults, environment overrides, and module binding syntax, see Configuration.