189 lines
6.2 KiB
Markdown
189 lines
6.2 KiB
Markdown
# 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 currently passed
|
|
only to lane extractors. 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).
|