18 KiB
CLI Reference
This is the canonical contract for invoking Scriptorium. Configuration discovery, precedence, application source locations, and server settings are defined in the configuration reference. The HTTP API reference owns service request and response behavior.
Shortest Useful Command
go run ./cmd/scriptorium render \
--config ./examples/config.yml \
--prompt generic.markdown_summary \
--input transcript=./examples/fixtures/transcript.md \
--input glossary=./examples/fixtures/glossary.yml
render prepares a request without calling an LLM.
Commands
scriptorium run: prepare a prompt, call the configured LLM, and write the generated artifact.scriptorium render: prepare a prompt and write prepared-run output.scriptorium serve: start the HTTP server.scriptorium inspect prompt: inspect one prompt definition without model execution.scriptorium inspect profile: inspect one effective profile without model execution.scriptorium inspect configuration: validate or inspect Promptkit's captured framework configuration.scriptorium config validate: validate application configuration without building an engine.scriptorium config show: show the resolved application configuration.scriptorium config sources: show the ordered configuration sources.scriptorium config explain: explain one effective or historical configuration path.
All command families accept --config <path> and --config-overlay <name>;
positional arguments are rejected. --config-overlay selects one application
configuration overlay; it is separate from --profile, which selects a
Promptkit execution profile. See configuration composition
for name, root, and no-base behavior. run, render, serve, inspect prompt,
inspect profile, and inspect configuration accept repeated
--promptkit-source <path> flags and --schema-dir <dir> where applicable.
They replace the configured source sequence in flag order. --prompt-dir and
--profile-dir are no longer supported; use promptkit_sources in application
configuration or the repeated source flags. Application config commands
remain independent of framework source loading. Explicit application flags,
including empty values, override file settings. Configuration load diagnostics
go to stderr and exit with status 1; successful load warnings are printed once
before command work.
scriptorium run
scriptorium run [flags]
Required flags:
| Flag | Meaning |
|---|---|
--prompt <id> |
Prompt ID to execute. |
Optional flags:
| Flag | Meaning |
|---|---|
--config <path> |
Application configuration file. |
--config-overlay <name> |
Selected application configuration overlay. |
--promptkit-source <path> |
PromptKit source file or directory; repeat to select ordered sources. |
--schema-dir <dir> |
Schema base-directory override. |
--prompt-version <version> |
Optional prompt-definition version selector. |
--profile <id> |
Execution-profile override. |
--session-id <id> |
Optional direct session identifier. |
--input name=path |
Optional input file mapping; repeat or use comma-separated mappings. |
--var name=value |
Template-variable mapping; repeat or use comma-separated mappings. |
--out <path> |
Write generated content to this file instead of stdout. |
--execution-report <path> |
Write an opt-in terminal execution report as newline-terminated JSON to a separate file. |
--llm-base-url <url> |
Runtime endpoint override. |
--model <name> |
Runtime model override. |
--api-key-env <name> |
Runtime API-key environment-variable name override. |
--temperature <float> |
Runtime temperature override. |
--max-tokens <int> |
Runtime maximum-token override. |
--top-p <float> |
Runtime top-p override. |
--reasoning-effort <value> |
Runtime reasoning-effort override. |
--timeout <duration> |
Runtime timeout override using Go duration syntax. |
--run-timeout <duration> |
Optional whole-run engine deadline using Go duration syntax; zero or omission adds no deadline, negative values are invalid. |
--transient-retries <integer> |
Nonnegative additional transient attempt count for this request; 0 disables additional attempts. |
Deprecated aliases: --prompt-id for --prompt, and --profile-id for
--profile.
Omitted numeric runtime flags preserve the selected effective value; explicit
zero values override it. --timeout 0s disables the per-attempt generation deadline
only; the caller context and configured transport cap remain active. CLI
durations are converted to whole seconds by truncation toward zero, so any
duration whose absolute value is below one second becomes an explicit
zero-second override. The timeout layers are defined in the
Promptkit outbound integration contract.
With the built-in client, each transient retry gets a fresh generation timeout;
this flag does not limit the complete run.
--run-timeout keeps subsecond precision and starts immediately before engine
execution. It bounds preparation, capacity waits, retry waits, generation, and
repairs where they honor context. Parsing, engine construction, and output
writes are outside that interval. A failed run whose execution context reaches
this deadline exits 1 with a safe deadline diagnostic; a completed invalid
output still exits 2. It does not promise immediate interruption of synchronous
work.
Omitting --transient-retries inherits the application setting or Promptkit's
current default of two additional attempts. The flag overrides only this
request; it does not alter the configured engine. Structural repair generations
have separate transient retry budgets.
There is no raw API-key flag. Use --api-key-env.
--prompt-version is passed directly to Promptkit. When it is omitted, the
selected prompt ID must have exactly one available version. --input is
optional at the CLI boundary: Promptkit decides whether the selected definition
requires declared inputs or template-referenced values.
--session-id supplies a direct, non-secret session identifier. A nonblank
value replaces a definition-rendered session ID; an omitted or blank value lets
the definition supply one. Promptkit trims direct values and limits them to 256
Unicode code points. Use stable, non-sensitive identifiers because effective
session IDs may appear in prepared output, run metadata, and provider-facing
requests.
--reasoning-effort is presence-aware: omitting it inherits the selected
profile value, a nonblank value replaces that value, and
--reasoning-effort= explicitly clears inherited reasoning. Promptkit treats
nonblank values as provider-specific opaque strings.
Execution report file
--execution-report requires a nonempty path. It is available only for run;
- is an ordinary filename. Parent directories are not created. An existing
file is replaced through ordinary file writing, without rollback or an atomic
replacement guarantee. Generated content still goes to stdout or --out.
Equal output/report paths, including existing paths that refer to the same
file, are rejected before execution.
The file is written after engine execution when Promptkit supplies a terminal event, including for a failed run or invalid generated output. A failure before invocation leaves the report path untouched. If no terminal event is supplied, Scriptorium leaves the path untouched and emits a diagnostic; an existing file may therefore contain an older report. Artifact output is attempted first on a successful run, and report writing is attempted even if artifact writing fails. Any output or report write failure exits 1; already-written output is not undone. Without a write failure, the actual run keeps its usual exit status.
The HTTP API reference defines the shared report fields and usage-presence semantics. The file contains that JSON object followed by a newline.
The report excludes content, credentials, URLs, headers, and raw errors, but its identifiers can still be sensitive. The caller owns file retention and access.
scriptorium render
scriptorium render [flags]
--prompt <id> is required. The following optional flags are supported:
--config, --config-overlay, repeatable --promptkit-source, --schema-dir, --prompt-version, --profile,
--input, --var, --out, --llm-base-url,
--model, --api-key-env, --temperature, --max-tokens, --top-p,
--reasoning-effort, --session-id, --timeout, --transient-retries, and --format text|json. Their meanings match the corresponding
run flags; --format selects prepared-run output and otherwise uses
defaults.render_format.
The same deprecated aliases and numeric/timeout behavior as run apply.
The same session and reasoning inheritance, replacement, and clearing behavior
also applies.
render validates the retry override but does not generate model output or
include a retry field in prepared output.
render resolves profiles and schemas as part of preparation but
does not call an LLM.
scriptorium serve
scriptorium serve [flags]
Optional flags:
| Flag | Meaning |
|---|---|
--config <path> |
Application configuration file. |
--config-overlay <name> |
Selected application configuration overlay. |
--addr <listen-address> |
HTTP listen-address override. |
--promptkit-source <path> |
PromptKit source file or directory; repeat to select ordered sources. |
--schema-dir <dir> |
Schema base-directory override. |
--artifact-root <dir> |
Root for HTTP file input references. |
--max-request-bytes <n> |
Maximum encoded HTTP request-body bytes; 0 disables the limit. |
--max-artifact-bytes <n> |
Maximum HTTP file-input artifact bytes; 0 disables the limit. |
--max-response-bytes <n> |
Maximum encoded HTTP response bytes; 0 disables the limit. |
serve accepts no runtime model override flags. HTTP request fields, response
schemas, and error codes are defined in the HTTP API reference.
scriptorium inspect prompt
scriptorium inspect prompt --prompt ID [--prompt-version VERSION]
[--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out PATH]
--prompt is required. Inspection uses normal configuration discovery and the
selected Promptkit sources, defaults to text regardless of
defaults.render_format, and writes to stdout unless --out is supplied.
Both definition-inspection commands first construct the same engine used for execution from the complete selected source sequence. Construction resolves and validates all effective definitions, including unused ones, and captures referenced message-file contents and static template syntax. Invalid unused definitions or unreadable message resources can therefore prevent inspection. No prompt collection is mandatory, but selected prompts are not ignored.
Inspection does not prepare an execution request, load request-time schemas or artifacts, resolve credential values, reserve backend capacity, or call a model. Prompt inspection does not select an execution profile or render request-specific templates.
scriptorium inspect profile
scriptorium inspect profile --profile ID
[--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out PATH]
--profile is required. After the full-source engine construction described
above, inspection selects one effective profile
with resolved inheritance and backend defaults. Unset provider controls are
shown as zero values when Promptkit leaves them unspecified.
Application configuration inspection
scriptorium config validate [flags]
scriptorium config show [flags]
scriptorium config sources [flags]
scriptorium config explain --path JSON_POINTER [flags]
Each accepts --config, --config-overlay, --schema-dir, --addr,
--artifact-root, --max-request-bytes,
--max-artifact-bytes, and --max-response-bytes. These are application
configuration selectors and overrides; request, credential, backend-editing,
output-format, and output-file flags are not accepted. Positional arguments
are rejected.
validate writes no success output; status 0 means the application configuration
loaded and passed its own validation. It does not establish that selected
Promptkit sources can construct an engine, credentials are present, or a
provider is available. show writes ConfigKit's resolved YAML snapshot. sources
writes one newline-terminated JSON array of source records in load order. Each
record has id, label, and layer, plus path when available; explicit CLI
overrides appear as synthetic sources. Defaults-only input without overrides
produces [] for sources.
explain requires an explicitly supplied --path in JSON Pointer syntax.
The empty string selects the root; /server/addr selects a field; ~1 and
~0 escape / and ~ inside mapping keys. Numeric tokens are interpreted
according to the containing mapping or sequence. Dotted paths, file paths,
and URL fragments are not accepted. ConfigKit writes a human-readable account
of the effective value and its chronological default, file/import, overlay,
CLI, normalization, and removed-value history. This is not a JSON schema or a
byte-for-byte stable prose format. Unknown and malformed paths exit 1 without
successful explanation output.
Diagnostics and warnings go to stderr, never into successful stdout. Parse, load, output, and diagnostic-write failures exit 1. Ordinary output writes may leave partial data on failure. Application inspection can contain paths and configured values; protect its output accordingly. Raw API-key values are not accepted by the application configuration schema.
Framework configuration inspection
scriptorium inspect configuration validate [flags]
scriptorium inspect configuration show [flags]
scriptorium inspect configuration sources [flags]
scriptorium inspect configuration explain --path JSON_POINTER [flags]
Each operation accepts --config, --config-overlay, repeatable
--promptkit-source, and --schema-dir. These flags select the application
settings and framework sources; positional arguments, --format, and --out
are not accepted. Unlike config validate, framework validate constructs
the Promptkit engine and validates all effective definitions, including
unused ones. It writes nothing on success and does not prepare a request,
resolve a credential, or contact a provider.
show writes Promptkit's native effective YAML, an inspection snapshot rather
than a promised reloadable file. sources writes a
newline-terminated JSON array in captured source order. Each source record has
id, label, layer, kind, and underlay_index, plus path when available
and imported_from for imported sources. That nested object has source_id,
line, and column. Values and output structure are a projection of the
captured Promptkit view, not Scriptorium's application-source records.
explain requires an explicitly supplied --path in ConfigKit JSON Pointer
syntax; --path '' selects the root. For example,
/profiles/team~1summary/model addresses the model field of the literal
profile ID team/summary. Escape / as ~1 and ~ as ~0; dots in a key
remain literal. Malformed and unknown pointers exit 1 without a successful
report. Explanation prose is native and is not a stable machine-readable
format.
Framework show and explain use Promptkit's native redaction for its
classified credential-shaped provider fields, including historical values.
Environment-variable reference names and ordinary provider parameters remain
visible. Arbitrary prompt or provider content is not classified as secret by
name inspection, so treat these reports as sensitive. This redaction policy is
limited to framework configuration reports; it does not add redaction to
inspect profile or prepared-run output. Credentials are not resolved by any
of these inspection operations. Promptkit owns detailed field and source
semantics; see its tagged format reference.
Warnings and errors go to stderr. Successful validate writes nothing to
stdout; successful show, sources, and explain write their reports there.
Parse, load, path, and output failures exit 1. A native writer error may leave
partial output.
Input And Variable Syntax
--input name=path maps an input name to a local file; --var name=value
maps a template variable to a string. Both flags can be repeated or contain
comma-separated mappings. Values may contain = after the first separator.
Empty names and values are rejected.
CLI inputs are file references. HTTP inline inputs are defined by the HTTP API reference.
Output And Exit Behavior
runwrites generated content to stdout, or to--outwhen supplied, and writes a concise summary to stderr. The summary includesbackend=<id>when Promptkit selected a backend; endpoint-only profiles omit it.renderwrites prepared-run output to stdout, or to--outwhen supplied, without a success summary. Text output includesselected_backend_idafterselected_profile_idwhen Promptkit selected one; endpoint-only profiles omit it.servewrites startup and server errors to stderr.
Exit statuses:
| Status | Meaning |
|---|---|
0 |
Success. |
1 |
Parse, configuration, loading, rendering, generation, output-write, or other runtime error. |
2 |
run generated and wrote output, but validation failed. |
A backend admission rejection is a runtime error and prints run error: model backend capacity is exhausted. The HTTP capacity response is defined in the
HTTP API reference.
Workflows And Examples
The maintained render script is a
copyable render workflow. The HTTP request example
is for a running serve process.