Unify CLI configuration selection and overrides
This commit is contained in:
237
docs/cli.md
237
docs/cli.md
@@ -1,198 +1,71 @@
|
||||
# Audita CLI Reference
|
||||
|
||||
## Shortest Useful Command
|
||||
The shared version-2 configuration parser is implemented for `process`, `config
|
||||
validate`, and `config print-effective`. Profile assembly and process execution are
|
||||
being reconnected in later work, so the CLI is not yet a usable assembled command.
|
||||
The [configuration reference](config.md) owns fields, defaults, and validation.
|
||||
|
||||
## Commands and help
|
||||
|
||||
```sh
|
||||
audita process transcript.json --glossary glossary.yaml --output corrected.json
|
||||
audita process <transcript.json> --glossary <glossary.yml> [flags]
|
||||
audita config validate --config <config.yml> [flags]
|
||||
audita config print-effective [flags]
|
||||
```
|
||||
|
||||
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.
|
||||
Root invocation, `--help`, `-h`, and command help succeed without loading a config
|
||||
file or resolving secrets. Unknown commands and flags return exit code `2`.
|
||||
`process` accepts exactly one transcript path, either before the flags or after
|
||||
them. With flags first, put the transcript last. Both config commands reject
|
||||
positional arguments and process-only flags.
|
||||
|
||||
## Command Overview
|
||||
All three commands accept `--config <path>` and `--overlay <name>`. `config validate`
|
||||
requires an explicit nonempty `--config`; the other commands select the explicit
|
||||
file, then `/usr/local/etc/audita/config.yml`, then `/etc/audita/config.yml`.
|
||||
Missing system candidates are skipped; inaccessible selected files are errors.
|
||||
No file means a configuration error. `AUDITA_CONFIG` is ignored. The selected
|
||||
overlay is loaded beside the main file, not used to locate profile files.
|
||||
|
||||
- `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.
|
||||
## Setting overrides
|
||||
|
||||
General help:
|
||||
Only flags actually supplied override file or overlay settings. `--modules ''`
|
||||
clears the module pipeline, and an explicit numeric zero reaches configuration
|
||||
validation. The shared setting flags are:
|
||||
|
||||
```sh
|
||||
audita --help
|
||||
audita process --help
|
||||
audita config --help
|
||||
```
|
||||
| Setting | Flags |
|
||||
| --- | --- |
|
||||
| Profile selection | `--proposal-profile`, `--validation-profile` |
|
||||
| Pipeline and output | `--modules`, `--output-schema` |
|
||||
| Validation budget | `--validation-max-prompt-tokens` |
|
||||
| Chunking | `--target-sections`, `--max-section-tokens`, `--min-section-tokens` |
|
||||
| Normalization (numeric seconds) | `--normalize-max-segment-gap`, `--normalize-ellipsis-gap`, `--normalize-max-segment-duration`, `--normalize-max-segment-tokens` |
|
||||
| Confidence thresholds | `--glossary-confidence-threshold`, `--homophones-confidence-threshold`, `--spoken-word-confidence-threshold`, `--grammar-confidence-threshold` |
|
||||
| Context | `--transcript-description` |
|
||||
| Diagnostics | `--work-dir`, `--work-dir-retention` |
|
||||
|
||||
## `process`
|
||||
`process` alone accepts `--glossary` (required), `--output`, and `--report-json`.
|
||||
Per-role model, base URL, key, timeout, retry, and concurrency flags have been
|
||||
removed. Models and generation controls belong to PromptKit profiles, backend
|
||||
credentials and capacity to configuration, and retry/deadline settings to the
|
||||
shared LLM section. Legacy configuration environment overrides are ignored.
|
||||
|
||||
Usage:
|
||||
## Streams and exit status
|
||||
|
||||
```sh
|
||||
audita process <transcript.json> [flags]
|
||||
```
|
||||
`config validate` prints `config is valid` on success. `config print-effective`
|
||||
currently writes ConfigKit's redacted effective-settings YAML; selected-profile
|
||||
and provenance views are scheduled with profile assembly. The effective YAML is
|
||||
for inspection and is not guaranteed to be a reloadable input file.
|
||||
|
||||
Input requirements:
|
||||
- exactly one transcript JSON positional argument is required;
|
||||
- `--glossary <path>` is required.
|
||||
For `process`, `--output` writes the corrected transcript to a file and leaves
|
||||
stdout empty on success. Without it, stdout carries transcript JSON only on
|
||||
success. `--report-json` writes a separate report file. Stderr carries readable
|
||||
errors and diagnostic locations. A successful run can contain skipped corrections
|
||||
or warnings; see the [report contract](integrations/output-files.md).
|
||||
|
||||
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.
|
||||
Exit codes are `0` for success, `1` for runtime or output failure, and `2` for
|
||||
usage or configuration input errors. Configuration commands never contact a
|
||||
provider merely to parse settings; profile validation is being connected next.
|
||||
|
||||
[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`.
|
||||
See the [input files](integrations/transcript-glossary-files.md),
|
||||
[subprocess contract](integrations/subprocess.md), and
|
||||
[artifact lifecycle](operations.md) for their respective details.
|
||||
|
||||
@@ -7,7 +7,11 @@ examples will be migrated with that integration.
|
||||
|
||||
## Loading and precedence
|
||||
|
||||
The application selects one main YAML file. ConfigKit loads built-in defaults,
|
||||
The application selects one main YAML file: an explicit `--config`, then
|
||||
`/usr/local/etc/audita/config.yml` if present, then `/etc/audita/config.yml`
|
||||
if present. Missing system candidates are skipped; an explicit missing or empty
|
||||
path, inaccessible selected file, or absence of any selected file is an error.
|
||||
`config validate` requires an explicit file. ConfigKit loads built-in defaults,
|
||||
the selected file, an optional named overlay from `overlays/<name>.yml` beside the
|
||||
main file, and only explicitly supplied setting overrides, in that order. Imports
|
||||
and secret-directory bootstrap are disabled. Unknown fields and missing, null,
|
||||
|
||||
@@ -147,7 +147,15 @@ Do not duplicate ConfigKit's exhaustive YAML/merge tests.
|
||||
|
||||
## Stage 2: Replace CLI Configuration Selection and Overrides
|
||||
|
||||
**Status:** Pending. **Depends on:** Stage 1.
|
||||
**Status:** Complete (2026-09-24). Added one parser for all three commands,
|
||||
strict file discovery, optional overlay selection, and visited-only setting
|
||||
overrides; removed retired flags and legacy process flag extraction. Updated CLI
|
||||
and configuration references. Isolated parser/loading tests passed with
|
||||
`go test internal/cli/config_input.go internal/cli/config_input_test.go`, and
|
||||
`git diff --check` passed. `go test ./internal/cli` remains unbuildable because
|
||||
the old runtime, validators, and diagnostics still use removed configuration
|
||||
fields; assembled command checks remain deferred to later stages.
|
||||
**Depends on:** Stage 1.
|
||||
**Owns:** `internal/cli/run.go`, `process_flags.go`, configuration command parsing,
|
||||
and corresponding CLI/subprocess tests.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user