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 slot=path] [--without-reference slot]
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 slot=path: bind a reference path to an extractor reference slot. Repeatable. Use lane.slot=path when multiple selected lanes declare the same slot.
• --without-reference slot: remove a configured optional reference binding. Repeatable. Use lane.slot when multiple selected lanes declare the same slot.

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 artifact lanes before the run starts. Flat slot names are accepted only when exactly one selected lane declares that slot. Binding paths are recorded in resolved pipeline metadata; reference file content is not read by the current runner.

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.