Files
scriptorium/docs/cli.md

11 KiB

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 owns standard family grammar and reports. Configuration owns discovery, settings, and source composition; the HTTP API owns the service contract. Existing callers should read the CLI migration guide.

Commands

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.

Commands that consume configuration accept --config PATH and --overlay NAME. An explicitly empty config value remains explicit; overlay names follow ConfigKit selection. 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 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.

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.