18 KiB
CLI Reference
This is the canonical reference for Notarius invocation, command inputs, reports, and outcome codes. Configuration owns fields, defaults, resource selection, and module keys; Operations owns runtime state; integration contracts own domain payloads.
Notarius uses native CommandKit commands with ckconfig and ckprompt. The upstream CLI reference 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.
Command Summary
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
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.
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.
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 for the shared rules.
Configuration Selection
--config PATH fixes the main source; explicit empty fails instead of discovering
another file. Omission uses configuration discovery.
Commands that support --overlay NAME select the native application overlay.
Configuration and pipeline commands also expose repeated --set POINTER=JSON:
notarius config show --config examples/dnd-minimal/config.yml \
--set /concurrency/workers=1 --path /concurrency/workers --format json
The value is JSON, so strings require JSON quoting. Preserve shell quoting:
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
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:
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
Run
notarius run PIPELINE_ID --input-file PATH [flags]
notarius pipeline run PIPELINE_ID --input-file PATH [flags]
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.
| 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 defines
directory defaults; Operations owns capture lifecycle.
Example using the maintained minimal configuration and input:
notarius run dnd-session --config examples/dnd-minimal/config.yml \
--input-file examples/dnd-minimal/transcript.json --format json
This run uses a configured provider and needs its credentials when required. Offline validation does not.
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
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.
For a complete D&D workflow, pipeline-level references are first-class inputs:
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 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.
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
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, orall.
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
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, preview, requirements, resource listings, and smoke tests.
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.
| 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 for library conventions.