scriptorium/docs/integrations/subprocess.md

Subprocess Integration

This document defines the supported subprocess contract for downstream applications invoking Scriptorium through the public CLI.

This is a CLI contract. Go callers that want an in-process typed API should use the package guide.

Supported Commands

Downstream applications should invoke:

• scriptorium render for preflight/debug output without LLM execution.
• scriptorium run for generation.

scriptorium serve is an HTTP service command, not the recommended subprocess contract for per-request execution.

Recommended Invocation Shapes

Render:

scriptorium render \
  --config <config_path> \
  --prompt <prompt_id> \
  --input transcript=<path> \
  --format json

Run:

scriptorium run \
  --config <config_path> \
  --prompt <prompt_id> \
  --input transcript=<path> \
  --out <artifact_path>

Callers may add:

• --profile <profile_id>
• repeatable --input name=path
• repeatable --var name=value
• runtime overrides when explicitly needed, such as --model, --llm-base-url, --api-key-env, and --timeout

Do not pass raw API keys as command arguments.

Config And Directory Behavior

Callers can rely on resolved app config or pass explicit paths.

Default config search order:

1. /usr/local/etc/scriptorium/config.yml
2. /etc/scriptorium/config.yml

Rules:

• Explicit --config requires file existence and valid syntax.
• CLI flags override config values.
• run and render require an effective prompt_dir.
• profile_dir is optional because built-in profiles are available.

Profile Selection

Profile selection follows runner behavior:

1. explicit --profile
2. prompt default_profile
3. error if neither is available

Treat prompt and profile IDs as deployment configuration, not hardcoded business logic.

Input And Variable Contract

• Inputs use repeated --input name=path.
• Input names must match prompt definition input names.
• Variables use repeated --var name=value.
• Both flags also accept comma-separated mappings.
• Prefer file inputs for large content.

CLI inputs are file references. HTTP-only inline references are documented in the HTTP API reference.

Environment Contract

• Pass through required API-key environment variables referenced by api_key_env.
• Keep subprocess environments scoped to required variables.
• Use --api-key-env only to name an environment variable.
• Never pass raw API keys via argv.

Stdout And Stderr

run:

• stdout: generated artifact body unless --out is used.
• stderr: success summary and errors.

render:

• stdout: prepared-run output unless --out is used.
• stderr: errors.

Capture stdout and stderr separately. Do not parse stderr as a stable data format beyond exit status handling.

Exit Status Contract

• 0: success.
• 1: parse, config, load, render, generation, IO, or runtime error.
• 2: run completed and output was written, but validation failed.

A run exit code 2 can still produce output on stdout or at --out. Consumers must decide whether to keep or discard that output.

Security Notes

• Treat generated artifacts, rendered prompts, stdout, and stderr as potentially sensitive.
• Use controlled output paths and access controls for persisted artifacts.
• Avoid logging full rendered prompts or generated artifacts by default.

Canonical References

• CLI behavior: CLI reference
• Config and file formats: Configuration reference
• Operations: Operations guide
• Troubleshooting: Troubleshooting