scriptorium/docs/cli.md

CLI Reference

This is the canonical contract for invoking Scriptorium. Configuration discovery, precedence, directories, profiles, and schemas 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.

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.
--input name=path	Input file mapping; repeat or use comma-separated mappings.

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.
--profile <id>	Execution-profile override.
--var name=value	Template-variable mapping; repeat or use comma-separated mappings.
--out <path>	Write generated content to this file instead of stdout.
--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.
--timeout <duration>	Runtime timeout override using Go duration syntax.

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-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 outbound integration contract.

There is no raw API-key flag. Use --api-key-env.

scriptorium render

scriptorium render [flags]

--prompt <id> and at least one --input name=path are required. The following optional flags are supported: --config, --prompt-dir, --profile-dir, --profile, --var, --out, --llm-base-url, --model, --api-key-env, --temperature, --max-tokens, --top-p, --timeout, 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. 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.

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.
• render writes prepared-run output to stdout, or to --out when supplied, without a success summary.
• 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.

Workflows And Examples

The maintained render script is a copyable render workflow. The HTTP request example is for a running serve process.