audita/docs/cli.md

Audita CLI Reference

Shortest Useful Command

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

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.

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

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

Flag descriptions identify their settings; defaults, accepted keys, numeric constraints, and inheritance rules are owned by configuration. 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 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
• 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

Configuration Commands

config validate

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 and validation boundaries.

config print-effective

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