# CLI Reference

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

## Quick Run

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

```text
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 pipeline module
  binding to use 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. 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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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](operations.md).

## `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:

```sh
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:

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

Validator chain overrides are configured on `chunk`, lane `extract`, lane
`merge`, and lane `normalize` bindings. Validator keys are resolved against the
registered validator catalog.

For YAML structure, Scriptorium profile sources, environment overrides, and
module binding syntax, see [Configuration](config.md).