scriptorium/docs/cli.md

CLI Reference

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 the prompt, loads input artifacts, resolves the execution profile, and prints the prepared request without calling an LLM.

Command Overview

• scriptorium run: prepare a prompt, call the configured LLM, write generated output, and print a run summary.
• scriptorium render: prepare a prompt only; write prepared-run output as text or json.
• scriptorium serve: start the HTTP server for POST /v1/runs.

Canonical related references:

• Configuration reference
• HTTP API reference
• Subprocess integration

Common Rules

• --config is supported by run, render, and serve.
• Positional arguments are rejected.
• run and render require --prompt, at least one --input, and an effective prompt_dir.
• serve requires an effective prompt_dir.
• profile_dir is optional. Without it, only built-in profiles are available.
• If profile_dir is set, custom profiles override built-in profiles with the same ID.
• Prompt cache control, session_id, structured output, and provider-specific profile fields are configured in YAML, not with CLI flags.

Config precedence is:

1. built-in defaults
2. config file values
3. CLI flags

Flag Reference

scriptorium run

scriptorium run [flags]

Required through flags or config:

• --prompt-dir <dir>: prompt definition directory.

Required as flags:

• --prompt <id>: prompt ID to execute.
• --input name=path: input file mapping. Repeat or use comma-separated mappings.

Optional flags:

• --config <path>: application config file.
• --profile-dir <dir>: custom profile definition directory.
• --schema-dir <dir>: schema base directory for json_schema validation.
• --profile <id>: execution profile override. If omitted, the prompt default_profile is used.
• --var name=value: template variable mapping. Repeat or use comma-separated mappings.
• --out <path>: write generated artifact body to a 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 max tokens override.
• --top-p <float>: runtime top-p override.
• --timeout <duration>: runtime timeout override using Go duration syntax, such as 30s or 2m.

Deprecated aliases:

• --prompt-id <id>: alias for --prompt.
• --profile-id <id>: alias for --profile.

Runtime override notes:

• Omitted numeric override flags preserve the selected profile/default value.
• Explicit zero values override the selected profile/default value.
• --timeout 0s disables the outbound HTTP client timeout for that request.
• There is no raw API-key flag; use --api-key-env.

scriptorium render

scriptorium render [flags]

Required through flags or config:

• --prompt-dir <dir>: prompt definition directory.

Required as flags:

• --prompt <id>: prompt ID to render.
• --input name=path: input file mapping. Repeat or use comma-separated mappings.

Optional flags:

• --config <path>: application config file.
• --prompt-dir <dir>: prompt definition directory.
• --profile-dir <dir>: custom profile definition directory.
• --profile <id>: execution profile override.
• --var name=value: template variable mapping. Repeat or use comma-separated mappings.
• --out <path>: write prepared-run output to a file instead of stdout.
• --llm-base-url <url>: runtime endpoint override for the prepared request.
• --model <name>: runtime model override for the prepared request.
• --api-key-env <name>: runtime API-key environment variable name override.
• --temperature <float>: runtime temperature override.
• --max-tokens <int>: runtime max tokens override.
• --top-p <float>: runtime top-p override.
• --timeout <duration>: runtime timeout override using Go duration syntax.
• --format text|json: prepared-run output format. Defaults to config defaults.render_format, then text.

Deprecated aliases:

• --prompt-id <id>: alias for --prompt.
• --profile-id <id>: alias for --profile.

Notes:

• render resolves profiles, loads schemas for json_schema prompts, and validates api_key_env.
• render does not accept --schema-dir; use config schema_dir for render-time schema lookup.
• render does not call the LLM.

scriptorium serve

scriptorium serve [flags]

Required through flags or config:

• --prompt-dir <dir>: prompt definition directory.

Optional flags:

• --config <path>: application config file.
• --addr <listen-address>: HTTP listen address.
• --prompt-dir <dir>: prompt definition directory.
• --profile-dir <dir>: custom profile definition directory.
• --schema-dir <dir>: schema base directory for json_schema validation.
• --artifact-root <dir>: base directory for HTTP file input references.
• --max-request-bytes <n>: maximum HTTP request body bytes; 0 disables the limit.
• --max-artifact-bytes <n>: maximum HTTP file artifact bytes; 0 disables the limit.
• --max-response-bytes <n>: maximum encoded HTTP response body bytes; 0 disables the limit.

Notes:

• serve does not accept runtime model override flags such as --model or --llm-base-url.
• HTTP request fields and error codes are documented in the HTTP API reference.
• HTTP file input references are rejected unless an artifact root is configured.
• HTTP size-limit flags affect only serve.

Input And Variable Syntax

• --input name=path maps prompt input names to local file paths.
• --var name=value maps prompt template variables to string values.
• Both flags can be repeated.
• Both flags also accept comma-separated mappings, such as --input transcript=./t.md,glossary=./g.yml.
• Values may contain = after the first separator, such as --var note=a=b=c.
• Empty names and empty values are rejected.

CLI run and render convert every --input mapping to a file artifact reference. HTTP also supports inline input references; see HTTP API reference.

Output Behavior

run:

• Writes generated artifact content to stdout by default.
• Writes generated artifact content to --out when provided.
• Prints a success summary to stderr.
• Prints errors to stderr on failure.

render:

• Writes prepared-run output to stdout by default.
• Writes prepared-run output to --out when provided.
• Does not print a success summary.

serve:

• Logs startup and server errors to stderr.

Exit Codes

• 0: success.
• 1: parse, config, load, render, generation, output-write, or runtime error.
• 2: run completed and wrote output, but validation status is failed.

Common Workflows

Render prompt inputs and variables as JSON:

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 \
  --var session_date=2026-05-04 \
  --format json

Run a prompt with an explicit profile and file output:

go run ./cmd/scriptorium run \
  --config ./examples/config.yml \
  --prompt generic.markdown_summary \
  --profile local-fast \
  --input transcript=./examples/fixtures/transcript.md \
  --input glossary=./examples/fixtures/glossary.yml \
  --out ./summary.md

Start the HTTP server with example config:

go run ./cmd/scriptorium serve --config ./examples/config.yml

Copyable maintained script:

• examples/render-markdown-summary.sh