# 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]
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.

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.

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).