# Subprocess Integration

This document covers process-boundary behavior for callers that invoke
Scriptorium as a child process. Command syntax, flags, output, and exit codes
are defined by the [CLI reference](../cli.md). Interface selection belongs in
the [consumer integration overview](../consumers/api.md).

## Process Contract

Use `scriptorium render` when the caller needs prepared output without a model
call, and `scriptorium run` for generation. Pass an explicit `--config` or
make the configuration search paths available to the child process; configuration
discovery, fields, profile selection, and credential mechanisms are defined in
the [configuration reference](../config.md).

Pass required API-key environment variables through the child environment. Do
not place raw API keys in arguments. Keep the environment limited to the values
needed for the selected profile.

For application-only preflight, invoke `scriptorium config validate`; it exits
0 with empty stdout when the application configuration loads, but does not
prove that Promptkit sources or credentials are usable. `config show` emits
resolved YAML and `config sources` emits newline-terminated JSON provenance.
All three use the same source selection and explicit overrides as execution
commands and require separate stderr capture for diagnostics. Their output can
include source paths, identifiers, credential reference names, and ordinary
backend parameters; treat it as potentially sensitive.

## Streams And Output Ownership

Capture stdout and stderr separately. Stdout contains the requested artifact or
prepared output unless the caller selects an output file; stderr contains
summaries, diagnostics, and server messages. The exact destinations and status
meanings are part of the [CLI reference](../cli.md), not a stable stderr data
protocol.

When using `--out`, the caller owns the output path, its permissions, and
cleanup. Treat rendered prompts, generated artifacts, stdout, and stderr as
potentially sensitive.

For `run`, an optional [execution report file](../cli.md) contains terminal
metadata separate from generated stdout or `--out`. The caller owns that
path's permissions and retention. Output and report files are not a
transaction: one may be written when the other fails, and a preexisting report
may remain when the invocation has no terminal event. Check the exit status
and diagnostics rather than assuming a report path contains this run's data.

## Cancellation And Recovery

A CLI invocation performs one synchronous request and creates no durable run
state. A supervising process that needs cancellation must terminate the child
process according to its own process-management policy. A later invocation is a
new request and can make another model call; there is no resume or checkpoint
protocol.

For `run`, callers may set the [whole-run deadline](../cli.md) to bound the
engine invocation. It is separate from the per-attempt generation timeout and
does not include child startup or output writing. A deadline failure exits 1;
supervisors still own process termination when they need to stop the child
outside that engine interval.

For deployment, filesystem permissions, and sensitive-artifact handling, see
the [operations guide](../operations.md).