# 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] [--resume] [--recompute-step step-id] [--debug [--debug-dir path]] [--llm-profile id] [--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. This retains its existing behavior for
  implicit single-step pipelines; explicit multi-step pipelines reject it
  rather than inferring dependency closure.
- `--resume`: request checkpoint reuse for this invocation. Checkpoint recording
  must be enabled in configuration. See
  [Operations](operations.md#checkpoint-cache) for prerequisites and reuse
  behavior.
- `--recompute-step step-id`: with `--resume` and checkpoint recording enabled,
  force the named ordered step and every transitive dependent lane to execute.
  Compatible required predecessors and unrelated lanes remain reusable. The
  value may identify an explicit step or the implicit single-step ID `default`;
  it cannot be combined with `--only`.
- `--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#state-surfaces) for the persistent setting, precedence,
  and cache-root selection.
- `--output-dir path`: output root. Defaults to `./notarius-output`.
- `--debug`: allocate and retain one debug bundle for this invocation.
- `--debug-dir path`: debug-bundle root override. This flag requires `--debug`.
- `--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. A debug-enabled run also
prints `debug=<bundle-path>`. If the run completes with warnings, the warning
count is printed to stderr.

Reference flags are external file bindings resolved against selected chunk,
extractor, merger, and normalizer targets before the run starts. Generated
artifact bindings are configured in ordered steps and cannot be introduced by a
CLI path flag. 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-minimal.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-minimal.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --reference spells.extract.glossary=./campaign-glossary.txt
```

For the maintained ordered D&D workflow, use the explicit pipeline. The first
step produces normalized NPC and scene-description artifacts; the second step
receives the NPC artifact in memory for spell extraction, combat extraction, and
combat normalization, and receives the required scene-description artifact for
combat eligibility:

```sh
go run ./cmd/notarius run dnd-session \
  --config examples/dnd-complete.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --output-dir ./npc-grounded-output
```

The generated NPC content remains contextual grounding, not spell or combat
evidence. It is represented in manifests and debug summaries by bounded
identity and producer provenance, not by payload content or a filesystem path.
The scene-description artifact is control context: combat extraction calls its
LLM only for an exact `combat` scene match. See the
[D&D combat-turn artifact contract](integrations/dnd-combat-turn-artifacts.md)
for the resulting empty-output and warning behavior.

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-minimal.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-minimal.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --session-id campaign-17-session-04
```

When `cache.checkpoints.enabled` is `true`, runs record checkpoints whether or
not `--resume` is present. Add the resume flag to load and reuse compatible
recorded work; using it while checkpoint recording is disabled is an error:

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

To selectively rerun one ordered step and its dependent lanes, use the step ID
from the configuration. The selected step and dependents are reported as
`forced_recompute`; reusable predecessors are reported as `reused`:

```sh
go run ./cmd/notarius run dnd-session \
  --config examples/dnd-complete.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --resume --recompute-step extract-events
```

Checkpoint decisions use these categories: `reused`, `executed`,
`forced_recompute`, and `dependency_invalidated`. The reason code and bounded
detail identify the decision without exposing reference content, local paths,
or secrets. `--recompute-step` requires checkpoint recording and `--resume`;
unknown step IDs, empty values, and combinations with `--only` are rejected.
The operator meanings of checkpoint reason codes are maintained in
[Operations](operations.md#resume-and-selective-recompute).

Use `--debug` to retain the redacted summary and trace bundle for one run. The
bundle is allocated before pipeline resolution; once allocated, its path is
also printed to stderr if the command fails. Debug-write failures cause exit
code `1`.

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

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

```sh
go run ./cmd/notarius run dnd-session \
  --config examples/dnd-minimal.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-minimal.config.yml \
  --input examples/seriatim-minimal-transcript.json \
  --chunk_cache bypass
```

`--diagnostics-dir` has been removed. For checkpoint behavior, durable output,
debug-bundle lifecycle, 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-minimal.config.yml

go run ./cmd/notarius config validate \
  --config examples/dnd-minimal.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-minimal.config.yml

go run ./cmd/notarius pipelines list \
  --config examples/dnd-minimal.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 a requested
  debug bundle 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).