audita/docs/cli.md

Audita CLI Reference

Shortest Useful Command

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:

audita --help
audita process --help
audita config --help

process

Usage:

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.

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
• transcript/glossary file contract: docs/integrations/transcript-glossary-files.md

process Examples

Write corrected transcript to a file:

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

Emit transcript JSON to stdout:

audita process transcript.json --glossary glossary.yaml

Use explicit config and write report JSON:

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

Override the module sequence:

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

config validate

Usage:

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:

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.