# 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](../consumers/pkg-scriptorium.md).

## 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:

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

Run:

```bash
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](../api.md).

## 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](../cli.md)
- Config and file formats: [Configuration reference](../config.md)
- Operations: [Operations guide](../operations.md)
- Troubleshooting: [Troubleshooting](../troubleshooting.md)