# CLI Reference

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

## Quick Run

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

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

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

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

For durable output, diagnostics, retention, and failure inspection, see
[Operations](operations.md).

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:

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

The production CLI does not currently register validator modules.

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