# 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 configured glossary selections, following the [process examples](../cli.md#processing). 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 `--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. Choose a trusted configuration bundle. An explicit main path still allows its configured imports and automatic overlay, glossary, and prompt companions. Without a main path, Audita uses the configured discovery locations. The parent controls who can write those sources and which report destinations and retained debug directories the invocation will use. Native inspection is separate from processing preflight. 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. Optional `--progress` messages arrive on stderr during stage and chunk execution, including model operations and completions. Debug enables progress by default, and `--progress=false` or quiet mode suppresses it. Consume progress as human-readable telemetry. Stdout remains the transcript stream. ## Result Handling Interpret the exit result according to the [CLI output and exit contract](../cli.md#inspection-and-outcomes). Consume transcript/report data through the [output-file contract](output-files.md), and treat stderr as human-readable detail. Audita loads configuration and parses the input transcript before report initialization. Early destination failures can also leave no reports. After initialization, failed reports can describe partial processing or output failures and use the same 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#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#inspection-and-outcomes)