Files
scriptorium/docs/cli.md

187 lines
11 KiB
Markdown

# CLI Reference
Scriptorium uses CommandKit v0.7.0, ckconfig v0.9.0, and ckprompt v0.10.0.
This document owns application invocation and delivery behavior. The pinned
[upstream CLI contract][native-cli] owns standard family grammar and reports.
[Configuration](config.md) owns discovery, settings, and source composition;
the [HTTP API](api.md) owns the service contract.
Existing callers should read the [CLI migration guide](consumers/upgrading-cli.md).
## Commands
```text
scriptorium run PROMPT_ID [flags]
scriptorium serve [flags]
scriptorium config scopes
scriptorium config validate|show|sources|explain|diff [flags]
scriptorium promptkit list prompts|profiles|backends|namespaces|collections [flags]
scriptorium promptkit show prompt|profile|backend ID [flags]
scriptorium promptkit requirements show|validate PROMPT_ID [flags]
scriptorium promptkit show prepared PROMPT_ID [flags]
scriptorium promptkit test KIND [flags]
scriptorium help [COMMAND ...]
scriptorium version
scriptorium completion bash|zsh|fish
```
Native help is also available with `--help`. Help, version, scope discovery,
and static completion do not load configuration or contact a provider.
Version/revision metadata is supplied by the build; ordinary builds identify
themselves as `dev` with no revision. Release build mechanics belong to the
[release procedure](release.md).
Commands that consume configuration accept `--config PATH` and `--overlay NAME`.
An explicitly empty config value remains explicit; overlay names follow
[ConfigKit selection](config.md#explicit-imports-and-selected-overlays).
There are no source/schema convenience flags or legacy command aliases.
Native shared `--format`, `--quiet`, `--verbose`, `--debug`, and progress
controls retain their upstream meanings. Diagnostics use stderr, not stdout.
Verbose exposes emitted Info and Warning messages without changing result bytes.
## Generation
`run` requires exactly one positional prompt ID. It has no duplicate prompt
flag or direct backend-selection flag; choose a profile for backend routing.
It uses these native bindings, with the preferred aliases below. Canonical
spellings prepend `llm-` (for example, `--llm-profile`).
| Preferred flags | Meaning |
| --- | --- |
| `--profile ID`, `--session-id ID` | Profile selection and optional non-secret session context. |
| `--var KEY=VALUE` | Repeatable caller-variable mappings. |
| `--input-text NAME=TEXT`, `--input NAME=TEXT` | Repeatable literal input mappings; `--llm-input` is also a literal-text alias. |
| `--input-file NAME=PATH` | Repeatable file references. |
| `--endpoint URL`, `--model NAME` | Native endpoint/model overrides. |
| `--temperature N`, `--max-tokens N`, `--top-p N` | Presence-aware numeric overrides, including zero. |
| `--timeout-seconds N` | Integer per-attempt generation timeout; zero disables that deadline, not caller cancellation or the transport cap. |
| `--reasoning-effort VALUE`, `--service-tier VALUE` | Native provider controls; an explicit empty reasoning value is preserved. |
| `--api-key-env NAME` | Credential environment-variable name, never raw key bytes. |
| `--extra-params JSON` | Native JSON-object provider parameters. |
| `--transient-retries N` | Request retry override; omission leaves the engine default. |
| `--prompt-namespace NAME`, `--profile-namespace NAME`, `--backend-namespace NAME` | Independent native namespace views. Qualified resource IDs remain exact; stored references are not rewritten. |
Mappings split at the first `=`; commas and subsequent equals signs are literal.
Repeat flags for multiple mappings. The last text/file occurrence for the same
input wins in command-line order. PromptKit validates selected definitions,
inputs, namespaces, provider settings, and credential requirements; Scriptorium
does not add an execution-readiness preflight or configurable default namespace.
Native string/pointer override semantics remain upstream-owned.
Application-owned generation controls:
| Flag | Meaning |
| --- | --- |
| `--run-timeout DURATION` | Go duration passed unchanged to PromptKit's operation budget. Positive values cover engine preparation/execution, including cooperative waits and repairs. Zero, omission, and negative values add no budget. Parsing, configuration/engine setup, and delivery are outside it. |
| `--report PATH` | Additionally write the returned native result to a separate file. |
| `--report-format text\|yaml\|json` | Explicit separate-report format; omission leaves native automatic rendering selected. |
The operation budget is independent of the integer per-attempt timeout.
Earlier parent cancellation/deadlines still apply. Cancellation is cooperative;
synchronous work that ignores context cannot be forcibly interrupted.
### Results And Separate Reports
The main report goes through the invocation reporter to stdout. Automatic/text
output is exactly `Artifact.Body`, with no added newline, header, escaping, or
summary. JSON/YAML output is the full native PromptKit `RunResult`, without a
Scriptorium envelope. In native structured serialization, artifact bytes use
the upstream representation (JSON base64), not an application text projection.
Save main output with shell redirection or the subprocess stdout destination.
There is no `--output` or `--out` flag. Omit `--quiet` when capturing the main
result: native quiet suppresses it even when stdout is redirected.
`--report` renders the same result through CommandKit without the artifact-only
text template. Its format is independent of stdout's `--format` and the filename
extension. Omission passes an unset format to the upstream renderer; it currently
renders structured values as YAML in automatic/text mode. Choose an explicit
format when required rather than relying on that upstream default.
The requested file is written even in quiet mode. Omission creates no separate
report. An explicitly empty path is a usage error before generation; `-` is an
ordinary filename. New files use mode 0644 subject to umask, existing files use
normal OS replacement behavior, and parent directories are not created.
Render, write, and close failures are reported.
Only a returned result is eligible for delivery. A resultless failure leaves an
existing report untouched; it does not synthesize an invocation-error result.
Main delivery is attempted first, then the requested report even if main
delivery fails. Writes are nontransactional; bytes already written remain.
Callers own redirected paths, retention, and keeping main and report destinations
separate. A shell may truncate its redirected file before the process starts.
## Application Configuration Inspection
The native `config` family defaults to `app`; select `--scope promptkit` for
captured framework configuration or use native scope discovery/all-scope modes.
`app` uses the actual completed ConfigKit result and does not construct an engine.
Native `--set POINTER=JSON` is enabled only for `app`. Records go directly to
ConfigKit: duplicate and ancestor/descendant-overlapping paths are rejected,
not resolved by flag order. No application-specific configuration flags or
custom `--against-*` counterparts are installed.
Native diff uses independent `--against-config`, `--against-overlay`, and
supported `--against-set` selections. Omitted right-side values do not inherit
the left side. See the [upstream contract][native-cli] for focused paths,
metadata discovery, source IDs, findings, explanations, and detailed comparisons.
## Framework Configuration Inspection
The `promptkit` config scope loads application settings selected by `--config`
and `--overlay`, constructs an engine, and exposes its captured native view.
It does not accept temporary overrides; native capability checks also apply
when an all-scope operation requests them.
Framework effective/explanation views retain native classified-field redaction,
including history. Environment-reference names and ordinary values remain
visible. This is not arbitrary secret detection and does not redact all prompt,
prepared, application, or generated content. Protect reports accordingly.
## Discovery, Preview, And Explicit Smoke Testing
Inventories retain native defaults and `--namespace`/`--all-namespaces` filters.
Named inspections expose native prompt messages and profile/backend values;
prepared preview exposes rendered content, not a summary projection.
Requirements discovery works before input artifacts exist and without schema
loading, credential resolution, message rendering, or provider access. It still
loads configuration and captured message resources. Reports preserve exact names,
metadata, variable presence (including empty values), completeness, and issue
codes. Partial discovery may succeed with status zero; completeness is not
binding satisfaction or execution readiness. Concrete validation and preview
keep their native preparation-time prerequisites and make no generation call.
Smoke-test kinds are `reachability`, `authentication`, `text_inference`,
`structured_output`, or `all`, with native aliases as documented upstream.
These explicit commands may contact providers and incur cost. Their presence
does not add a startup/provider probe. Read the native findings: unsuccessful or
unsupported checks are not automatically invocation failures.
## Server And Statuses
`serve` accepts configuration selection and presence-aware HTTP controls:
`--addr`, `--artifact-root`, `--max-request-bytes`, `--max-artifact-bytes`,
and `--max-response-bytes`. It has no generation request controls. Values and
defaults belong to [configuration](config.md).
Interrupt/SIGTERM cancels the invocation context. The server closes its listener
and active connections; canceled shutdown returns operational status, with no
graceful-drain deadline or guarantee that context-ignoring work has finished.
| Status | Meaning |
| --- | --- |
| 0 | Native success, subject to successful presentation/delivery. |
| 1 | Operational failure, including lookup/preparation/generation/capacity, cancellation/timeouts, unclassified load errors, and delivery failure for an otherwise successful run. |
| 2 | Native usage/declaration-input errors, or configuration errors classified as invalid input by native diagnostic evidence. |
| 3 | Native `config diff --check` found differences. |
| 4 | Completed generation returned `ValidationFailed`; artifact and native result remain deliverable. |
Native finalization handles presentation errors: success/usage become operational;
an already nonzero domain outcome retains its classification/status. A report-file
failure preserves completed-validation status 4 while adding its explanation and
cause. An operational failure to perform validation is status 1, not status 4.
JSON selection does not turn failures into a separate JSON error envelope.
[native-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md