audita/docs/cli.md

Audita CLI Reference

The shared version-2 configuration parser and offline profile inspection serve process, config validate, and config print-effective. The configuration reference owns fields, defaults, and validation; the migration guide maps retired inputs.

Commands and help

audita process <transcript.json> --glossary <glossary.yml> [flags]
audita config validate --config <config.yml> [flags]
audita config print-effective [flags]
audita version

Root invocation, --help, -h, and command help succeed without loading a config file or resolving secrets. Unknown commands and flags return exit code 2. process accepts exactly one transcript path, either before the flags or after them. With flags first, put the transcript last. Both config commands reject positional arguments and process-only flags.

All three commands accept --config <path> and --overlay <name>. config validate requires an explicit nonempty --config; the other commands select the explicit file, then /usr/local/etc/audita/config.yml, then /etc/audita/config.yml. Missing system candidates are skipped; inaccessible selected files are errors. No file means a configuration error. AUDITA_CONFIG is ignored. The selected overlay is loaded beside the main file, not used to locate profile files.

audita version prints audita <version> and a newline to stdout, with no application configuration or provider setup. It returns 0 on success with empty stderr. help version, version -h, and version --help print command usage to stdout and return 0. Help follows standard flag parsing and can short-circuit trailing arguments. Other invalid invocations return 2 with a usage error on stderr. The command uses ReleaseKit's public buildinfo.Version() accessor. It reports an injected release identifier when present, otherwise the executable's main-module version when available and not (devel), and dev when neither source provides a release identifier.

Setting overrides

Only flags actually supplied override file or overlay settings. --modules '' clears the module pipeline, and an explicit numeric zero reaches configuration validation. The shared setting flags are:

Setting	Flags
Profile selection	--proposal-profile, --validation-profile
Pipeline and output	--modules, --output-schema
Validation budget	--validation-max-prompt-tokens
Chunking	--target-sections, --max-section-tokens, --min-section-tokens
Normalization (numeric seconds)	--normalize-max-segment-gap, --normalize-ellipsis-gap, --normalize-max-segment-duration, --normalize-max-segment-tokens
Confidence thresholds	--glossary-confidence-threshold, --homophones-confidence-threshold, --spoken-word-confidence-threshold, --grammar-confidence-threshold
Context	--transcript-description
Reporting	--reporting[=true|false], --report-dir DIR
Debug	--debug[=true|false], --work-dir DIR

process alone accepts --glossary (required) and --output. An omitted or empty output value selects stdout. Nonempty output filenames are used literally, including whitespace. Reporting defaults to enabled. --reporting=false disables all three ordinary reports; an explicit false overrides a true file or overlay setting. For stdout output, reports use the effective reporting.stdout_dir, which defaults to the invocation working directory. For file output, they go beside the transcript unless --report-dir is explicitly supplied. The flag selects the report directory for either transcript destination; a config-file or overlay value for reporting.stdout_dir alone affects stdout output only. A selected report directory must be nonblank when reporting is enabled. With reporting disabled, the report destination is inactive and is not probed. --debug separately enables retained detailed artifacts under --work-dir; selecting --work-dir alone does not enable capture. Configuration inspection does not create or probe these output directories. Per-role model, base URL, key, timeout, retry, and concurrency flags have been removed. Models and generation controls belong to PromptKit profiles, backend credentials and capacity to configuration, and retry/deadline settings to the shared LLM section. Legacy configuration environment overrides are ignored.

Streams and exit status

config validate loads settings and both selected PromptKit profiles offline, then prints config is valid on success. config print-effective accepts --view settings|profiles|explain and defaults to settings. Settings writes ConfigKit's redacted effective-settings YAML. Profiles writes an Audita-owned YAML summary of selected ID, backend, model, sampling controls, per-attempt timeout, service tier, and reasoning effort for each role. It omits credentials, endpoints, and arbitrary extra provider parameters. Explain writes a YAML sequence of field paths, source origins, and recorded derivations without resolved setting values. An inherited field may also include an inheritance sequence; each step identifies from, to, and reference paths as JSON pointers. These fields describe the effective inheritance chain without including configuration values. A direct child override reports its own source instead. Debug configuration origins use the same explanation shape. These views share the same settings and profile validation path as process. Unknown views are usage errors. The effective settings YAML is for inspection and is not guaranteed reloadable.

For process, --output writes the corrected transcript to a file and leaves stdout empty on success. Without it, stdout carries transcript JSON only on success. Enabled reporting creates errors.yml, recoveries.yml, and report.md in the selected directory. Successful stderr begins with Completed: N corrections applied; E work units with errors; R recoveries. Report and debug locations follow only when created. Model-operation failures can coexist with a completed run and applied corrections; read the YAML reports for details. Debug artifacts are created only with --debug. See the report contract.

Exit codes are 0 for success, 1 for runtime or output failure, and 2 for usage or configuration input errors. Invalid settings and profiles return 2; broken embedded assets, caller cancellation, fatal processing, and required output failures return 1. A late report-write failure can follow a published transcript; exit status and report status remain authoritative. Configuration commands inspect profiles without contacting a provider.

See the input files, subprocess contract, and artifact lifecycle for their respective details.