# Audita CLI Reference

## Shortest Useful Command

```sh
audita process transcript.json --glossary glossary.yaml --output corrected.json
```

This command runs the core workflow with your input files. For a copyable example
using maintained inputs and explicit prerequisites, see the [README](../README.md).
Commands here assume `audita` is on `PATH`; use `./bin/audita` after a local build.

## Command Overview

- `audita process`: process one transcript JSON file.
- `audita config validate`: validate a versioned YAML config file.
- `audita config print-effective`: print redacted effective config JSON.

General help:

```sh
audita --help
audita process --help
audita config --help
```

## `process`

Usage:

```sh
audita process <transcript.json> [flags]
```

Input requirements:
- exactly one transcript JSON positional argument is required;
- `--glossary <path>` is required.

Place the transcript path first, followed by flags, as shown above. Flag values
may use `--name value` or `--name=value`. Unknown flags or extra positional
arguments are errors. Flags before a final transcript path are also accepted;
do not interleave further flags after a positional argument consumed by the flag
parser.

[Configuration discovery and precedence](config.md#loading-model) determine the
initial settings; explicit process flags supply overrides. Configuration is loaded
before process help is printed, so invalid discovered configuration can also make
process help fail. Input formats belong to the
[input-file contract](integrations/transcript-glossary-files.md).

### `process` Flag Reference

Core I/O flags:
- `--config <path>`: path to versioned YAML config file.
- `--glossary <path>`: glossary YAML input path (required).
- `--output <path>`: corrected transcript JSON output file path.
- `--report-json <path>`: machine-readable report JSON output path.
- `--output-schema <key>`: output encoder selection; see [configuration](config.md#pipeline-and-output).
- `--modules <csv>`: comma-separated module sequence override.

Primary LLM flags:
- `--llm-api-key <value>`: primary LLM API key.
- `--model <name>`: primary LLM model name.
- `--base-url <url>`: primary OpenAI-compatible base URL.
- `--llm-timeout-seconds <int>`: primary timeout in seconds.
- `--max-retries <int>`: primary structured-output retries.

Validation LLM flags:
- `--validation-llm-api-key <value>`: validation LLM API key.
- `--validation-model <name>`: validation LLM model name.
- `--validation-base-url <url>`: validation OpenAI-compatible base URL.
- `--validation-llm-timeout-seconds <int>`: validation timeout in seconds.
- `--validation-max-retries <int>`: validation structured-output retries.
- `--validation-max-prompt-tokens <int>`: validation max prompt tokens.

Concurrency flags:
- `--total-llm-concurrency <int>`: total concurrent proposal+validation LLM calls.
- `--proposal-llm-concurrency <int>`: concurrent proposal-generation LLM calls.
- `--validation-llm-concurrency <int>`: concurrent validation LLM calls.
- `--llm-concurrency <int>`: alias for `--total-llm-concurrency`.

Chunking and normalization flags:
- `--target-sections <int>`: target number of transcript sections.
- `--max-section-tokens <int>`: maximum section tokens.
- `--min-section-tokens <int>`: minimum section tokens.
- `--normalize-max-segment-gap <float>`: maximum same-speaker merge gap.
- `--normalize-ellipsis-gap <float>`: gap threshold for ellipsis insertion.
- `--normalize-max-segment-duration <float>`: maximum merged segment duration.
- `--normalize-max-segment-tokens <int>`: maximum merged segment token estimate.

Threshold flags:
- `--glossary-confidence-threshold <float>`
- `--homophones-confidence-threshold <float>`
- `--spoken-word-confidence-threshold <float>`
- `--grammar-confidence-threshold <float>`

Context and diagnostics flags:
- `--transcript-description <text>`: background context for prompts; does not override transcript content.
- `--work-dir <path>`: per-run diagnostics work directory.
- `--work-dir-retention <value>`: retention selection; see [configuration](config.md#thresholds-context-and-diagnostics).

Flag descriptions identify their settings; defaults, accepted keys, numeric
constraints, and inheritance rules are owned by [configuration](config.md).
Normalization time flags use numeric seconds; LLM timeout flags use integer seconds.

### `process` Output and Exit Behavior

- With `--output`: stdout is expected to be empty on success.
- Without `--output`: stdout contains transcript JSON only on success.
- `--report-json` writes a file and is never printed to stdout.
- Stderr is human-readable diagnostics/errors.
- Processing failures include the diagnostics directory path when initialization
  succeeded. Later report-write or retention errors can omit that path.
- Output files may already exist when a later reporting or cleanup failure occurs.
- Rejected/skipped corrections and warnings can occur in a successful run; inspect
  the [report format](integrations/output-files.md#process-report) for details.
- Diagnostic wording is human-readable and is not a machine-stable JSON channel.

Exit behavior:
- `0`: success.
- `1`: runtime failure during processing/reporting/output or retention handling.
- `2`: CLI usage or configuration input error.

Integration references:
- subprocess contract: [`docs/integrations/subprocess.md`](integrations/subprocess.md)
- transcript/glossary file contract: [`docs/integrations/transcript-glossary-files.md`](integrations/transcript-glossary-files.md)

### `process` Examples

Write corrected transcript to a file:

```sh
audita process transcript.json \
  --glossary glossary.yaml \
  --output corrected.json
```

Emit transcript JSON to stdout:

```sh
audita process transcript.json --glossary glossary.yaml
```

Use explicit config and write report JSON:

```sh
audita process transcript.json \
  --glossary glossary.yaml \
  --config audita.yml \
  --output corrected.json \
  --report-json report.json
```

Override the module sequence:

```sh
audita process transcript.json \
  --glossary glossary.yaml \
  --modules glossary,homophones,grammar \
  --output corrected.json
```

## Configuration Commands

### `config validate`

```sh
audita config validate --config examples/minimal-config.yml
audita config validate --config examples/production-config.yml
```

The only command-specific flag is `--config <path>`, which is required.
Positional arguments are rejected. Success prints `config is valid` to stdout
and returns zero; usage, file-read, parse, and validation errors go to stderr and
return `2`. See [applied configuration sources](config.md#effective-precedence)
and [validation boundaries](config.md#examples).

### `config print-effective`

```sh
audita config print-effective --config examples/minimal-config.yml
```

The only command-specific flag is optional `--config <path>`. Positional
arguments are rejected. Without an explicit file, [discovery](config.md#loading-model)
applies. Success prints redacted configuration JSON to stdout and returns zero.
Usage and configuration errors return `2`; serialization or stdout-write failures
return `1`.

The printed JSON reflects the effective in-memory configuration; it is not a YAML
configuration file and is not the process-report schema. Use it to inspect merged
settings, not as a file to pass back to the YAML loader.

## Help

Root invocation without arguments and root help print usage successfully. Use
`--help` or `-h` for subcommand help. Help normally returns zero; process help has
the configuration-loading caveat described above. Unknown commands return `2`.