257 lines
8.9 KiB
Markdown
257 lines
8.9 KiB
Markdown
# CLI Reference
|
|
|
|
This is the canonical reference for the implemented Notarius command-line
|
|
interface.
|
|
|
|
## Quick Run
|
|
|
|
```sh
|
|
OPENROUTER_API_KEY=... \
|
|
go run ./cmd/notarius run dnd-session \
|
|
--config examples/dnd-spells.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json
|
|
```
|
|
|
|
The maintained example uses prompt defaults and Scriptorium's built-in
|
|
`mistral-small-3` profile, which reads `OPENROUTER_API_KEY`. To use another
|
|
endpoint or model, configure a Scriptorium profile source and select its profile
|
|
ID in config or with `--llm-profile`.
|
|
|
|
## Commands
|
|
|
|
```text
|
|
notarius help
|
|
notarius run <pipeline-id> --input path/to/source.json [--config path/to/config.yml] [--only lane-a,lane-b] [--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 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.
|
|
- `--resume`: reuse valid workspace checkpoints for this invocation. Requires
|
|
an effective workspace directory and `workspace.resume.enabled: true`.
|
|
- `--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. It does not change the workspace directory.
|
|
- `--llm-profile id`: override every effective LLM-capable pipeline module
|
|
binding to use one Scriptorium profile ID. Validator-specific profiles are
|
|
not overridden. Configured LLM-backed validators with explicit profiles are
|
|
validated against the configured Scriptorium profile source.
|
|
- `--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. 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, merger, 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;
|
|
- `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
|
|
```
|
|
|
|
Use `--resume` to reuse valid checkpoints from a previous compatible
|
|
invocation:
|
|
|
|
```sh
|
|
go run ./cmd/notarius run dnd-session \
|
|
--config examples/dnd-spells.config.yml \
|
|
--input examples/seriatim-minimal-transcript.json \
|
|
--resume
|
|
```
|
|
|
|
Plain `run` does not skip completed work. It executes the pipeline normally and
|
|
refreshes checkpoints when checkpointing is enabled. `--resume` verifies each
|
|
checkpoint before reuse and executes any missing, corrupt, or incompatible step
|
|
normally.
|
|
|
|
For 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, 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`
|
|
|
|
## Implemented Production Validators
|
|
|
|
The production CLI currently registers these validator keys:
|
|
|
|
- `generic/always_accept`
|
|
- `generic/always_reject`
|
|
- `generic/valid_json`
|
|
- `generic/valid_json_schema`
|
|
- `extract/dnd/spells/shape`
|
|
- `extract/dnd/spells/source_refs`
|
|
- `extract/dnd/spells/source_relatedness`
|
|
|
|
The production default chain for the `dnd/spells` extractor is:
|
|
|
|
1. `generic/valid_json`
|
|
2. `generic/valid_json_schema`
|
|
3. `extract/dnd/spells/shape`
|
|
4. `extract/dnd/spells/source_refs`
|
|
5. `extract/dnd/spells/source_relatedness`
|
|
|
|
Validator chain overrides are configured on `chunk`, lane `extract`, lane
|
|
`merge`, and lane `normalize` bindings. Omitted overrides use production
|
|
defaults, `validators: []` disables validation for that binding, and non-empty
|
|
lists replace the default chain in configured order. Validator keys are resolved
|
|
against the registered validator catalog.
|
|
|
|
For YAML structure, Scriptorium profile sources, environment overrides, and
|
|
module binding syntax, see [Configuration](config.md).
|