scriptorium/docs/integrations/subprocess.md

Subprocess Integration

Purpose

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

This is a CLI contract, not an internal Go package integration.

Supported Commands

Downstream applications should invoke:

• scriptorium run
• scriptorium render

Use run for generation.

Use render for preflight/debug output without LLM execution.

Recommended Invocation Shapes

Run:

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

Render:

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

Callers may add:

• --config <path>
• --profile <profile_id>
• repeatable --input name=path
• repeatable --var name=value
• runtime overrides when explicitly needed (--model, --llm-base-url, --timeout, etc.)

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
• explicit --config requires file existence and valid syntax
• CLI flags override config values

Profile Selection

Profile selection follows runner behavior:

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

Callers should treat prompt/profile IDs as deployment configuration, not hardcoded 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 for small metadata values.
• Prefer file inputs for large content.

Environment Contract

• Pass through required API-key environment variables referenced by api_key_env.
• Never pass raw API keys via CLI arguments.
• Keep subprocess environment scoped to required variables.

Output And Error Handling

run:

• stdout: artifact body unless --out is used
• --out: writes artifact to file
• stderr: success summary and errors

render:

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

Callers should capture stdout and stderr separately.

Exit Status Contract

• 0: success
• 1: parse/config/load/render/generation/IO/runtime error
• 2: run completed but validation failed

A run exit code 2 can still produce output (stdout or --out).

Security Notes

• Treat generated artifacts and stderr logs as potentially sensitive.
• Avoid logging full rendered prompts by default in production contexts.
• Use controlled output paths and access controls for persisted artifacts.

Canonical References

• CLI behavior: CLI reference
• Config behavior: Configuration reference
• Operations and failure handling: Operations guide, Troubleshooting