scriptorium/docs/cli.md

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.

All commands accept --config <path> and reject positional arguments. An effective prompt_dir is required for every command. Supply it through the configuration contract or the command's --prompt-dir flag.

scriptorium run

scriptorium run [flags]

Required flags:

Flag	Meaning
--prompt <id>	Prompt ID to execute.

Optional flags:

Flag	Meaning
--config <path>	Application configuration file.
--prompt-dir <dir>	Prompt-definition directory override.
--profile-dir <dir>	Custom profile-directory override.
--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 JSON object contains the following fields:

Field	Meaning
run_id, prompt_id, prompt_version, profile_id, backend_id, model	Terminal identifiers; absent values are omitted.
outcome	success, invalid_output, error, or other for an unrecognized upstream value.
failure	The known terminal failure category, none, or other for an unrecognized value.
status_code	Provider status, omitted when unavailable.
retries_exhausted	Boolean independent of the failure category.
attempts, transient_retries, repair_calls	Unsigned terminal aggregate counts.
duration_ms, capacity_wait_ms, generation_duration_ms, retry_delay_ms	Terminal observed durations in integer milliseconds; their sum need not equal wall time.
usage	Object containing prompt_tokens, completion_tokens, total_tokens, cached_tokens, and cache_write_tokens.

Each usage count contains value (integer), known (boolean), and complete (boolean). Reported zero differs from an unknown count; an incomplete total does not establish complete billing. All counts, durations, retries_exhausted, and usage are present even when zero or unknown. The recognized failure values are none, canceled, deadline, transport, provider_status, malformed_response, capacity, invalid_config, invalid_request, prompt_not_found, profile_not_found, prompt_load, profile_load, artifact_load, prompt_render, validation, generation, and other.

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, --prompt-dir, --profile-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 does not accept --schema-dir; configure schema_dir through the configuration file. It 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.
--addr <listen-address>	HTTP listen-address override.
--prompt-dir <dir>	Prompt-definition directory override.
--profile-dir <dir>	Custom profile-directory override.
--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] [--prompt-dir DIR] [--format text|json] [--out PATH]

--prompt is required. Inspection uses normal configuration discovery and a --prompt-dir override, defaults to text regardless of defaults.render_format, and writes to stdout unless --out is supplied. It loads and normalizes the selected definition but does not resolve a profile, load a schema, render a template, reserve backend capacity, or call a model.

scriptorium inspect profile

scriptorium inspect profile --profile ID
    [--config PATH] [--profile-dir DIR] [--format text|json] [--out PATH]

--profile is required; built-in profiles need no prompt directory. Inspection resolves profile inheritance and backend defaults, but never reads a credential value, loads a prompt, reserves capacity, or calls a model. Unset provider controls are shown as zero values when Promptkit leaves them unspecified.

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

• run writes generated content to stdout, or to --out when supplied, and writes a concise summary to stderr. The summary includes backend=<id> when Promptkit selected a backend; endpoint-only profiles omit it.
• render writes prepared-run output to stdout, or to --out when supplied, without a success summary. Text output includes selected_backend_id after selected_profile_id when Promptkit selected one; endpoint-only profiles omit it.
• serve writes 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.