audita/docs/cli.md

# Audita CLI Reference

## Shortest Useful Command

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

This command validates input files, runs the configured correction pipeline, and writes corrected transcript JSON.

## 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.

Config path selection for `process`:
1. `--config <path>`
2. `AUDITA_CONFIG`
3. `/usr/local/etc/audita/config.yml` (if present)
4. `/etc/audita/config.yml` (if present)

For precedence and full config schema, see [`docs/config.md`](config.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 schema key (`bare-segments` or `audita-v1`).
- `--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 <auto|always|never>`: run-directory retention policy.

### `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.
- On failures after diagnostics initialization, stderr includes the diagnostics directory path.

Exit behavior:
- `0`: success.
- `1`: runtime failure during processing/reporting/output paths.
- `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
```

## `config validate`

Usage:

```sh
audita config validate --config <path>
```

Behavior:
- validates defaults merged with file config;
- does not apply environment overrides;
- prints `config is valid` on success.

Errors:
- `--config` is required;
- positional arguments are rejected;
- validation failures are printed to stderr.

## `config print-effective`

Usage:

```sh
audita config print-effective [--config <path>]
```

Config path selection:
1. `--config <path>` when provided
2. `AUDITA_CONFIG`
3. `/usr/local/etc/audita/config.yml` (if present)
4. `/etc/audita/config.yml` (if present)

Behavior:
- merges defaults, optional config file, and environment overrides;
- prints redacted JSON to stdout.

Errors:
- positional arguments are rejected;
- resolution or parse failures are printed to stderr.