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 and formats the prompt without calling an LLM.

Command Overview

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

Integration references:

• HTTP contract
• Narratio subprocess contract

Common Argument Rules

• --config is supported by run, render, and serve.
• run and render require:
  • --prompt
  • at least one --input
  • an effective prompt_dir from flags or config
• serve requires an effective prompt_dir from flags or config.
• profile_dir is optional. If omitted, only built-in profiles are available; if provided, custom profiles override built-ins with the same ID.
• Built-in profile IDs are listed in the configuration reference.
• Positional arguments are rejected.
• Prompt cache control is configured in prompt YAML (messages[].cache_control), not with CLI flags.
• Provider-specific reasoning_effort and extra_params are configured in profile YAML or HTTP model overrides, not with CLI flags.

Flag Reference

scriptorium run

• --config <path>: app config file path.
• --prompt-dir <dir>: prompt definition directory.
• --profile-dir <dir>: custom profile definition directory.
• --schema-dir <dir>: schema base directory for json_schema validation.
• --prompt <id>: prompt ID to execute. Required.
• --prompt-id <id>: deprecated alias for --prompt.
• --profile <id>: explicit profile override.
• --profile-id <id>: deprecated alias for --profile.
• --input name=path: input mapping (repeatable, comma-separated accepted).
• --var name=value: template variable mapping (repeatable, comma-separated accepted).
• --out <path>: write artifact body to 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 (Go duration syntax, for example 30s, 2m).

Numeric runtime override flags are presence-aware:

• omitted numeric flags preserve the selected profile/default value
• explicit zero values override the selected profile/default value (--temperature 0, --max-tokens 0, --top-p 0, --timeout 0s)

scriptorium render

• Supports the same flags as run, except:
  • no --schema-dir flag.
• Adds:
  • --format text|json: prepared-run output format.

Notes:

• render still resolves profile and runtime settings.
• render still validates that api_key_env exists if the selected profile or overrides require it.

scriptorium serve

• --config <path>: app config file path.
• --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.

Notes:

• serve does not accept runtime model override flags such as --model or --llm-base-url.

Input And Variable Syntax

• --input name=path maps prompt input names to local file paths.
• --var name=value maps template variable names to values.
• If a prompt defines session_id: "{{ .session_id }}", pass the OpenRouter sticky-routing value with --var session_id=<value>.
• Both flags can be repeated.
• Both flags also support comma-separated batches, for example:
  • --input transcript=./t.md,glossary=./g.yml
  • --var session_id=42,session_date=2026-05-04

Output Behavior

run:

• Writes generated artifact content to stdout by default.
• Writes generated artifact content to --out when provided.
• Prints run summary metadata to stderr on success.
• Appends cached_tokens=<n> cache_write_tokens=<n> to the summary only when the provider reports non-zero cache usage.
• 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 line.

serve:

• Logs startup and server errors to stderr.

Exit Codes

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

When run exits 2, output may already be written to stdout or --out.

Common Workflows

Render prompt inputs and template 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 profile override 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 explicit config:

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

Copyable example script:

• examples/render-markdown-summary.sh