199 lines
7.4 KiB
Markdown
199 lines
7.4 KiB
Markdown
# 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`.
|