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

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

## 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 deployment, filesystem permissions, and sensitive-artifact handling, see
the [operations guide](../operations.md).