Files
notarius/docs/cli.md

368 lines
18 KiB
Markdown
Raw Normal View History

# CLI Reference
This is the canonical reference for Notarius invocation, command inputs, reports,
and outcome codes. [Configuration](config.md) owns fields, defaults, resource
selection, and module keys; [Operations](operations.md) owns runtime state;
integration contracts own domain payloads.
Notarius uses native CommandKit commands with ckconfig and ckprompt. The
[upstream CLI reference][native-cli] owns their general parser, report, inspection,
and smoke semantics. The examples below show Notarius-specific selections.
Use help for every installed command's current options.
2026-07-26 13:11:40 +00:00
## Command Summary
2026-07-26 13:11:40 +00:00
~~~text
notarius --help
notarius help pipeline run
notarius version
notarius completion bash
notarius pipeline list
notarius pipeline show PIPELINE_ID
notarius pipeline validate PIPELINE_ID
notarius pipeline run PIPELINE_ID --input-file PATH
notarius run PIPELINE_ID --input-file PATH
notarius config scopes
notarius config validate
notarius config show
notarius config sources
notarius config explain
notarius config diff
notarius promptkit list prompts
notarius promptkit show profile PROFILE_ID
notarius promptkit requirements show PROMPT_ID
notarius promptkit requirements validate PROMPT_ID
notarius promptkit show prepared PROMPT_ID
notarius promptkit test KIND
2026-07-26 13:11:40 +00:00
~~~
Bare invocation, `help`, `--help`, and `-h` display native help. Help also works
on subcommands without their execution-only required inputs. Help, version, and
Bash/Zsh/Fish completion need no configuration, credentials, or run storage.
2026-07-26 13:11:40 +00:00
`version` reports the application identity; `version --scope commandkit` selects
the library identity. Source-tagged installation and release-linked build identity
remain available; an unversioned checkout reports `development`. Version output
uses native report formats, not a custom root flag.
## Syntax And Supplied Values
Put flags after the **complete command path**, optionally interspersed with its
operands. Value flags accept `--name value` or `--name=value`. Boolean flags
accept presence and explicit values such as `--debug=false`. `--` ends option
parsing; later tokens are operands.
2026-07-26 13:11:40 +00:00
Singleton flags may repeat; the last successfully parsed occurrence supplies
the value. Every occurrence is parsed, so a malformed earlier value remains an
error. Repeatable flags retain occurrence order and do not split commas.
Omission differs from supplied empty, false, and zero. Semantic validity still
depends on the selected command and native request. See
[registered syntax][syntax] for the shared rules.
2026-07-26 17:22:27 +00:00
## Configuration Selection
2026-07-26 13:11:40 +00:00
`--config PATH` fixes the main source; explicit empty fails instead of discovering
another file. Omission uses [configuration discovery](config.md#configuration-discovery-and-precedence).
Commands that support `--overlay NAME` select the native application overlay.
Configuration and pipeline commands also expose repeated `--set POINTER=JSON`:
2026-07-26 13:11:40 +00:00
~~~sh
notarius config show --config examples/dnd-minimal/config.yml \
--set /concurrency/workers=1 --path /concurrency/workers --format json
2026-07-26 13:11:40 +00:00
~~~
The value is JSON, so strings require JSON quoting. Preserve shell quoting:
2026-07-26 13:11:40 +00:00
~~~sh
notarius pipeline validate dnd-session \
--config examples/dnd-minimal/config.yml \
--set '/pipelines/dnd-session/mode="permissive"' \
--set /pipelines/dnd-session/max_additional_turns=0
2026-07-26 13:11:40 +00:00
~~~
Assignments use non-root mapping paths, not sequence indexes. To change a record
inside a steps/resource list, use an appropriate source/overlay or replace the
complete list. Duplicate or overlapping assignments fail. Version and inheritance
controls are not assignment targets. Overrides follow native loading and recorded
resolution; they are not an alternate YAML parser. PromptKit commands expose
their own native selection/request flags; use help rather than assuming every
configuration flag applies to them.
## Pipeline Commands
`pipeline list` lists configured IDs in sorted order without module resolution
or engine construction. `pipeline show PIPELINE_ID` resolves modules, controls,
validator chains, static prompt dependencies, steps/lanes, and reference bindings,
without expanding every LLM profile or reading input/reference content.
`pipeline validate PIPELINE_ID` performs offline domain resolution and known
prompt/profile dependency checks using the shared load and engine when needed.
It requires no input transcript, reference file bytes, credential values,
provider call, or output/cache/debug directories. Partial profiles remain valid.
This is distinct from native configuration validation: request preparation and
dynamic selections are checked when used.
Show and validate accept configuration selection and native report controls.
They inspect the complete configured pipeline; lane selection belongs to run:
~~~sh
notarius pipeline list --config examples/dnd-complete/config.yml --format json
notarius pipeline show dnd-session --config examples/dnd-complete/config.yml
notarius pipeline validate dnd-session --config examples/dnd-complete/config.yml
2026-07-26 13:11:40 +00:00
~~~
### Run
2026-09-13 17:16:06 +00:00
~~~text
notarius run PIPELINE_ID --input-file PATH [flags]
notarius pipeline run PIPELINE_ID --input-file PATH [flags]
2026-09-13 17:16:06 +00:00
~~~
`run` is a native alias for `pipeline run`: both resolve to the same declaration
and handler. One pipeline ID and a nonempty `--input-file` are required.
2026-09-13 17:16:06 +00:00
| Run flag | Meaning |
| --- | --- |
| `--config PATH`, `--overlay NAME`, `--set POINTER=JSON` | Configuration selection above. |
| `--input-file PATH` | Required source input file. |
| `--lane ID` | Repeat to select literal artifact lane IDs; commas are part of an ID, not separators. |
| `--output-dir PATH` | Nonempty invocation-relative override of the output root. |
| `--cache auto\|bypass\|refresh` | Invocation-wide selection over binding and pipeline cache controls. |
| `--reference SELECTOR=PATH` | Repeatable external reference bind. |
| `--without-reference SELECTOR` | Repeatable external reference unbind. |
| `--debug[=true\|false]` | Native debug verbosity and independent run capture selection. |
| `--debug-dir PATH` | Capture destination override; explicit empty disables capture. |
| `--llm-profile ID`, `--llm-session-id ID` | Native resource/session selections below. |
| `--llm-*` execution controls | Run-wide request overrides below. |
| `--format`, `--quiet`, `--verbose`, `--progress` | Native presentation controls below. |
A directory alone does not enable capture. A nonempty debug-directory override
can re-enable capture over an empty configured root, but still needs debug
selection. `--debug --quiet` captures while suppressing stdout; `--quiet --debug`
selects debug visibility and capture. `--debug=false` disables capture. Debug
on inspection commands changes native visibility without allocating a pipeline
bundle. [Configuration](config.md#concurrency-output-cache-and-debug) defines
directory defaults; [Operations](operations.md) owns capture lifecycle.
Example using the maintained minimal configuration and input:
~~~sh
notarius run dnd-session --config examples/dnd-minimal/config.yml \
--input-file examples/dnd-minimal/transcript.json --format json
2026-09-13 17:16:06 +00:00
~~~
This run uses a configured provider and needs its credentials when required.
Offline validation does not.
2026-09-13 17:16:06 +00:00
### Run-wide LLM Overrides
These canonical ckprompt flags reach initial producers, semantic corrections,
and LLM validators on the shared native engine without mutating configuration:
| Flag | Value |
| --- | --- |
| `--llm-profile` | Exact profile ID; qualified for collection resources. |
| `--llm-session-id` | Session selection. |
| `--llm-endpoint` | Native endpoint override. |
| `--llm-model` | Model override. |
| `--llm-temperature` | Numeric temperature. |
| `--llm-max-tokens` | Integer token limit. |
| `--llm-top-p` | Numeric top-p. |
| `--llm-timeout-seconds` | Integer native request timeout. |
| `--llm-service-tier` | Service tier selection. |
| `--llm-reasoning-effort` | Reasoning selection; explicit empty suppresses inherited reasoning. |
| `--llm-api-key-env` | Credential environment-variable name, not its value. |
| `--llm-transient-retries` | Integer native transient-failure retry selection; explicit zero disables these retries. |
| `--llm-extra-params` | JSON provider-parameter object, preserving false/zero/null values. |
Omitted values remain unspecified, not the display defaults in help.
`--llm-temperature=0` and `--llm-reasoning-effort=` retain their supplied meaning.
Native target validation and provider-map rules apply; this interface does not
add a repair-model selection, structural-repair count, or generic stage retry.
Use application configuration for semantic turns and native prompt configuration
for structural contracts.
Omitted profile selection preserves binding/pipeline/prompt precedence.
Explicit `--llm-profile=` clears the application profile selection so native
prompt default selection applies. Without an explicit session flag, Notarius
generates a stable `notarius:v1:` session from the trimmed resolved input module
key and exact raw input bytes, independent of references and pipeline/profile
settings. An explicit value replaces it; explicit empty clears that generated
selection and leaves native prompt/session behavior in control. Sessions are
provider-visible correlation identifiers, not secret storage.
PromptKit convenience spellings are scoped to `promptkit` commands; run uses
the canonical `--llm-*` names above. [Native request validation][requests]
documents execution controls in detail.
### Reference Selectors
Bind declared slots using `--reference SELECTOR=PATH`:
| Selector | Target |
| --- | --- |
| `slot` | Every selected compatible target declaring the slot. |
| `chunk.slot` | Chunker. |
| `lane.slot` | Compatible extract/merge/normalize bindings in that lane. |
| `lane.extract.slot` | That lane's extractor. |
| `lane.merge.slot` | That lane's merger. |
| `lane.normalize.slot` | That lane's normalizer. |
Pipeline/lane selectors may match several targets and fail if they match none.
A binding-specific selector requires its selected target to declare the slot.
There is no stage-wide merger shorthand. CLI paths override configured external
paths; narrower selectors beat broader ones, with last occurrence winning at
equal scope. Binding and unbinding the same concrete target at equal scope fails;
narrower actions can make intentional exceptions to broader actions.
`--without-reference` uses the selector without `=PATH`. It removes external
bindings only. Neither action replaces/removes generated handoffs; collisions
fail resolution and required slots must remain bound. CLI paths use the invocation
working directory. Configuration defines slot compatibility and path origins in
[References And Ordered Handoffs](config.md#references-and-ordered-handoffs).
For a complete D&D workflow, pipeline-level references are first-class inputs:
~~~sh
notarius run dnd-session --config examples/dnd-complete/config.yml \
--input-file examples/dnd-complete/transcript.json \
--reference party=/data/references/party.txt \
--reference glossary=/data/references/glossary.txt \
--output-dir /data/results --format json
~~~
### Completion Report
Successful runs publish domain files and finalize requested capture before
reporting one small value:
| Field | Meaning |
| --- | --- |
| `pipeline` | Selected pipeline ID. |
| `artifact_count` | Published deliverable files, including reused artifacts and enabled auxiliaries; excludes intermediates/cache/debug. |
| `output_directory` | Absolute run-specific publication directory, not the configured root. |
| `debug_directory` | Optional absolute run capture directory; omitted when disabled. |
| `fallback_count` | Producer operations that emitted fallback, present only when positive. |
Text summarizes pipeline, count, and path, appending capture location when
available. Fallback success is explicitly qualified, even when warnings are
hidden. Affected downstream artifacts, attempts, and validators are not extra
fallbacks. JSON/YAML serialize the same value; report format does not change
domain artifact encoding. There is no persisted receipt, execution ledger,
universal envelope, or automatic duplicate report file.
Consumers check status, optionally decode the report, and read configured
lane/auxiliary paths. A failed stdout write may leave partial bytes. A failure
after publication can leave valid artifacts; the failure explanation identifies
available paths. [JSON output](integrations/json-output.md) owns logical artifact
paths and payload contracts, not this report.
## Configuration Commands
The native scopes are `app` (default) and `promptkit`. Both inspect the same
application-owned load; the latter focuses native PromptKit settings. Use
`config scopes` for supported operations. No inspection command implicitly runs
a pipeline or provider.
~~~sh
notarius config validate --config examples/dnd-minimal/config.yml
notarius config show --scope app --config examples/dnd-minimal/config.yml
notarius config sources --config examples/dnd-complete/config.yml
notarius config explain --config examples/dnd-minimal/config.yml \
--path /concurrency/workers --format json
notarius config show --scope promptkit --config examples/dnd-minimal/config.yml
notarius config diff --config examples/dnd-minimal/config.yml \
--against-config examples/dnd-complete/config.yml --check
~~~
Show supports `--path`; explain supports `--list`, `--path`, and native history/
filter options. Focused PromptKit paths retain the `/promptkit` prefix, for
example `/promptkit/collections/notarius/profiles`. Diff accepts separate
right-side configuration, overlay, and assignment inputs; differences with
`--check` yield status 3. These commands
report native values and secret-aware source evidence, not copied Notarius
inspection objects. Consult [native configuration commands][configuration]
for complete report and comparison semantics. Use `pipeline validate`, not
configuration validation, for production module/reference/resource preflight.
## PromptKit Commands
The installed native suite includes:
- listings of prompts, profiles, backends, namespaces, and collections;
- inspection of a named prompt, profile, or backend;
- requirements discovery, concrete request validation, and prepared preview;
- explicit smoke tests: `reachability`, `authentication`, `text_inference`,
`structured_output`, or `all`.
~~~sh
notarius promptkit list prompts --config examples/dnd-minimal/config.yml \
--namespace notarius
notarius promptkit show profile notarius/dnd-extraction \
--config examples/dnd-minimal/config.yml --format json
notarius promptkit requirements show notarius/dnd.spells \
--config examples/dnd-minimal/config.yml
2026-07-26 13:11:40 +00:00
~~~
Resource/requirements inspection needs no transcript, credential values, or
provider call. Profile reports describe the stored profile before backend
completion and request overrides; partial profiles are valid. Request validation
and `show prepared` actually prepare native requests and may read supplied
resources or require credentials according to the target, but do not call a
model. Prepared reports can contain rendered application data.
Use `--llm-var KEY=VALUE`, `--llm-input-text NAME=TEXT`, or
`--llm-input-file NAME=PATH` for concrete prompt inputs. These are not the
pipeline's source input. Namespace flags choose namespaces for short IDs;
already-qualified IDs remain unchanged. Native convenience aliases are installed
only on their applicable PromptKit commands; use help to see them.
Smoke tests are explicit and may contact providers or perform inference.
Read support, applicability, and observation results; status zero alone does
not mean every observation passed. Neither debug nor inspection silently
launches a smoke test. Full native mechanics are documented under
[inspection][inspection], [preview][preview], [requirements][requirements],
[resource listings][catalogs], and [smoke tests][smoke].
2026-07-26 13:11:40 +00:00
## Output Streams And Exit Statuses
Results go to stdout; failures, native diagnostics, and progress go to stderr.
`--format text|json|yaml` selects report presentation. Default run presentation
uses its human template; other structured native reports ordinarily use YAML.
`--format` does not reformat help, completion scripts, diagnostics, or domain
payloads.
Only one visibility mode is active; the last enabled `--quiet`, `--verbose`,
or `--debug` wins. Ordinary mode hides optional warning/info/debug messages;
verbose shows warning/info; debug adds debug and default progress. Explicit
`--progress=false` disables progress, and quiet suppresses it. Quiet suppresses
stdout but retains failure explanations; formatting errors can still fail a
quiet command. Run capture selection remains independent of that final mode.
`--format json --verbose` keeps successful stdout report-only JSON while useful
diagnostics go to stderr. No application-wide structured error envelope is
introduced; failed stdout is not a success document.
2026-07-26 17:22:27 +00:00
2026-07-26 13:11:40 +00:00
| Status | Meaning |
| --- | --- |
| `0` | Command completed, including supported permissive fallback with report qualification. |
| `1` | Operational failure, cancellation, publication/capture/presentation failure, or an unclassified/mixed failure. |
| `2` | Invalid invocation or identifiable invalid configuration. |
| `3` | Native configuration differences with diff check mode. |
Native causes and classification remain intact. Not every resource/preflight
failure is identifiable invalid configuration. Rendering or diagnostic delivery
failure can change an otherwise successful result to failure; callers check the
actual process status. See [native outcomes][outcomes] for library conventions.
[native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md
[syntax]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#registered-command-syntax
[configuration]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#configuration-scopes
[requests]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#concrete-request-validation
[inspection]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-definition-inspection
[preview]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-prepared-request-preview
[requirements]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-requirements
[catalogs]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-catalogs
[smoke]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#promptkit-smoke-testing
[outcomes]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md#outcome-status