# CLI Reference

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

For the minimal end-to-end invocation, see the [README](../README.md).

## Commands

```text
notarius help
notarius run <pipeline-id> --input path/to/source.json [--config path/to/config.yml] [--only lane-a,lane-b] [--chunk_cache auto|bypass|refresh] [--output-dir path] [--diagnostics-dir path] [--llm-profile id] [--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 uses the discovery
  rules in [Configuration](config.md#discovery).
- `--only lane-a,lane-b`: run only the named artifact lanes. Values are
  comma-separated and must be non-empty.
- `--resume`: request checkpoint reuse for this invocation. See
  [Operations](operations.md#checkpoints) for prerequisites and reuse behavior.
- `--chunk_cache auto|bypass|refresh`: select chunk-plan reuse for this
  invocation. `auto` reuses a valid plan by canonical source digest, `bypass`
  performs no plan-cache I/O, and `refresh` regenerates and replaces a valid
  plan only after chunk validation succeeds. See
  [Configuration](config.md#workspace) for the persistent setting, precedence,
  and cache-root selection.
- `--output-dir path`: output root. 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 with 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. For configured reference
bindings, precedence, path resolution, and validation, see
[Configuration](config.md#pipelines).

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

The resume flag can be added to an otherwise identical run invocation:

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

Use `refresh` when intentionally replacing the cached plan for the same source:

```sh
go run ./cmd/notarius run dnd-session \
  --config examples/dnd-spells.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --chunk_cache refresh
```

Use `bypass` for a one-off run that must not inspect or create plan-cache state:

```sh
go run ./cmd/notarius run dnd-session \
  --config examples/dnd-spells.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --chunk_cache bypass
```

For checkpoint behavior, 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, Notarius uses the discovery
  rules in [Configuration](config.md#discovery).
- `--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, Notarius uses the discovery
  rules in [Configuration](config.md#discovery).
- `--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.

For YAML structure, defaults, Scriptorium profile sources, environment
overrides, and selectable module and validator keys, see
[Configuration](config.md).