eric/audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Document the new configuration and processing workflow

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-10 17:52:14 +00:00
parent 926fa26a31
commit ba1d5d2367
61 changed files with 832 additions and 765 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
docs/cli.md
View File

@@ -1,116 +1,45 @@
# Audita CLI Reference
The shared version-2 configuration parser and offline profile inspection serve
`process`, `config validate`, and `config print-effective`.
The [configuration reference](config.md) owns fields, defaults, and validation;
the [migration guide](migrations/v2.md) maps retired inputs.
Audita uses CommandKit for routing and the ConfigKit and PromptKit integrations
for their standard inspection and request commands. Run `audita --help` or
command-specific `--help` for the installed command inventory. The adopted
[CommandKit consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/f369d6a78253b6e6fcb1e023fb2e9c3af1d20ff0/docs/consumers/guide.md)
describes the standard command grammar, inspection, comparison, preview,
validation, smoke tests, and their provider-specific caveats. Help and version
do not load application or model configuration.
## Commands and help
## Processing
```sh
audita process <transcript.json> --glossary <glossary.yml> [flags]
audita config validate --config <config.yml> [flags]
audita config print-effective [flags]
audita version
audita process [flags] transcript.json
```
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.
`--config` selects a main configuration and `--overlay` selects its overlay.
`--output` writes the transcript to a file; omission selects stdout. The shared
`--debug` flag enables retained debug artifacts, and `--quiet` suppresses optional
messages. Quiet processing requires an output file or `/dev/null`. See
[operations](operations.md) for output and report lifecycle.
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.
Explicit process flags override root settings only. `--glossaries` and
`--protected-terms` each accept one JSON array of collection names or `null`;
`[]` clears the selection. Set pipeline order and per-entry overrides in YAML.
Other supplied flags cover profiles, output schema, description, reporting,
chunking, normalization, confidence thresholds, validation budget, and debug
work directory. `audita process --help` lists the available flags. An omitted flag
does not contribute an override. [Configuration](config.md) defines their values
and inheritance.
`audita version` prints `audita <version>` and a newline to stdout, with no
application configuration or provider setup. It returns `0` on success with
empty stderr. `help version`, `version -h`, and `version --help` print command
usage to stdout and return `0`. Help follows standard flag parsing and can
short-circuit trailing arguments. Other invalid invocations return `2` with a
usage error on stderr. The command uses ReleaseKit's public
`buildinfo.Version()` accessor. It reports an injected release identifier when
present, otherwise the executable's main-module version when available and not
`(devel)`, and `dev` when neither source provides a release identifier.
## Inspection and outcomes
## Setting overrides
The application configuration scope uses ConfigKit's native effective values,
source evidence, explanation, comparison, and redaction. PromptKit supplies its
own configuration and resource scopes and request preparation, validation, and
explicit smoke diagnostics. Inspection does not require a processing-ready
pipeline or contact a provider. Smoke tests can contact providers and are run
only on explicit request.
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:
| 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` |
| Reporting | `--reporting[=true\|false]`, `--report-dir DIR` |
| Debug | `--debug[=true\|false]`, `--work-dir DIR` |
`process` alone accepts `--glossary` (required) and `--output`.
An omitted or empty output value selects stdout. Nonempty output filenames are
used literally, including whitespace.
Reporting defaults to enabled. `--reporting=false` disables all three ordinary
reports; an explicit false overrides a true file or overlay setting. For stdout
output, reports use the effective `reporting.stdout_dir`, which defaults to the
invocation working directory. For file output, they go beside the transcript
unless `--report-dir` is explicitly supplied. The flag selects the report
directory for either transcript destination; a config-file or overlay value for
`reporting.stdout_dir` alone affects stdout output only. A selected report
directory must be nonblank when reporting is enabled. With reporting disabled,
the report destination is inactive and is not probed. `--debug` separately
enables retained detailed artifacts under `--work-dir`; selecting `--work-dir`
alone does not enable capture. Configuration inspection does not create or
probe these output directories.
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.
## Streams and exit status
`config validate` loads settings and both selected PromptKit profiles offline,
then prints `config is valid` on success. `config print-effective` accepts
`--view settings|profiles|explain` and defaults to `settings`. Settings writes
ConfigKit's redacted effective-settings YAML. Profiles writes an Audita-owned
YAML summary of selected ID, backend, model, sampling controls, per-attempt
timeout, service tier, and reasoning effort for each role. It omits credentials,
endpoints, and arbitrary extra provider parameters. Explain writes a YAML
sequence of field paths, source origins, and recorded derivations without
resolved setting values. An inherited field may also include an `inheritance`
sequence; each step identifies `from`, `to`, and `reference` paths as JSON
pointers. These fields describe the effective inheritance chain without
including configuration values. A direct child override reports its own source
instead. Debug configuration origins use the same explanation shape. These views
share the same settings and profile validation path as `process`. Unknown views
are usage errors. The effective settings YAML is for inspection and is not
guaranteed reloadable.
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. Enabled reporting creates `errors.yml`, `recoveries.yml`, and
`report.md` in the selected directory. Successful stderr begins with
`Completed: N corrections applied; E work units with errors; R recoveries.`
Report and debug locations follow only when created. Model-operation failures
can coexist with a completed run and applied corrections; read the YAML reports
for details. Debug artifacts are created only with `--debug`. See the
[report contract](integrations/output-files.md).
Exit codes are `0` for success, `1` for runtime or output failure, and `2` for
usage or configuration input errors. Invalid settings and profiles return `2`;
broken embedded assets, caller cancellation, fatal processing, and required
output failures return `1`. A late report-write failure can follow a published
transcript; exit status and report status remain authoritative.
Configuration commands inspect profiles without contacting a provider.
See the [input files](integrations/transcript-glossary-files.md),
[subprocess contract](integrations/subprocess.md), and
[artifact lifecycle](operations.md) for their respective details.
Process stdout contains transcript JSON when no output file is selected. Ordinary
reports may record recoverable model failures even when processing completes.
Exit status `0` means success, `1` runtime or output failure, `2` invalid usage
or input, and native comparison may return `3` for differences. See the
[output contract](integrations/output-files.md) and [subprocess contract](integrations/subprocess.md).