# Subprocess Integration

This guide explains how a parent process can invoke Audita and consume its results.
The [CLI reference](../cli.md) owns command syntax, streams, and exit semantics;
[configuration](../config.md) owns discovery and precedence.

## Invocation

Use an argument array with the transcript path and required glossary argument,
following the [process examples](../cli.md#commands-and-help). For machine workflows,
select an explicit transcript file destination and a configuration path. Reports
go beside the transcript unless an explicit `--report-dir` selects another
directory. For stdout output, reports use the effective `reporting.stdout_dir`
(defaulting to the invocation working directory), including a `--report-dir`
override. A config-file or overlay value for `reporting.stdout_dir` alone does
not redirect file-output reports. `--work-dir` selects a debug root, while
configuration or `--debug` enables capture; the path flag alone does not.
Supplying a configuration path also makes file selection predictable; only
explicitly referenced credential variables are read from the environment.

Resolve the executable deliberately and set the child's working directory so
relative input/output paths and reported artifact paths have a known base.
Read stdout and stderr concurrently to avoid pipe blocking, and impose timeout
or cancellation in the parent process when needed.

## Result Handling

Interpret the exit result according to the
[CLI output and exit contract](../cli.md#streams-and-exit-status).
Consume transcript/report data through the
[output-file contract](output-files.md), and treat stderr as human-readable detail.
The three reports may be absent after early configuration or destination
failures. After initialization, failed reports can describe invalid input or
partial processing and use the same selected report directory as successful
runs. Exit `0` can include recoverable model errors and applied
corrections; inspect `errors.yml` and `recoveries.yml` for those outcomes. A
transcript may have been written before a later required report failure, so
the file alone does not prove completion.

If processing fails, preserve available evidence and follow
[operations recovery](../operations.md#failure-inspection-and-recovery).
Ordinary reports are independent of optional retained debug evidence. Parent
cancellation reaches the child through its context; Audita joins workers and
attempts failed-status report finalization before exiting. Uncatchable
termination can leave `in_progress` reports. Neither the existence of an output
file nor a debug directory alone establishes successful completion.

## Related Contracts

- [Transcript and glossary inputs](transcript-glossary-files.md)
- [LLM endpoint compatibility](openai-compatible-llm.md)
- [Configuration inspection commands](../cli.md#commands-and-help)