131 lines
3.6 KiB
Markdown
131 lines
3.6 KiB
Markdown
# 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)
|