audita/docs/internal/cli-config.md

Configuration and CLI Change Recipes

This document owns contributor editing and validation steps for configuration, CLI wiring, and maintained examples. Definitions of behavior belong to the configuration and CLI contracts.

Changing Configuration

1. Update fields, defaults, loading, and validation in internal/core/config.
2. Update file, environment, and CLI mapping as applicable, including CLI flag extraction. Preserve the source-specific behavior defined in the configuration contract, including the distinct validation and effective-config commands.
3. Update redaction when secrets are involved.
4. Review configuration tests and related CLI tests for precedence, validation, and source-specific behavior. Add or adjust tests for the changed contract according to the testing policy.
5. Update the configuration reference and affected examples.

Changing CLI Behavior

1. Implement parsing and wiring in internal/cli.
2. Preserve stream and exit contracts unless a change is intentional and documented. Review subprocess integration when changing output, error, or report handling.
3. Review internal/cli tests and cmd/audita subprocess tests; update coverage for the changed behavior.
4. Update the CLI reference and affected integration guidance.

Validating Examples

Keep complete copyable files in examples and link to them from their canonical contract documentation. Keep them valid and secret-free. From the repository root, validate the maintained configuration examples:

go run ./cmd/audita config validate --config examples/minimal-config.yml
go run ./cmd/audita config validate --config examples/production-config.yml
go run ./cmd/audita config print-effective --config examples/minimal-config.yml

The effective-config command incorporates environment settings; use a controlled environment when comparing its results. Check affected CLI examples against the parser and use schema tests for maintained transcript/glossary inputs. Example validation should not invoke a live LLM merely to check documentation.

Runtime Change Checks

Select checks according to the testing policy:

• Configuration or CLI changes: inspect internal/core/config tests, internal/cli tests, and cmd/audita integration tests.
• Process/output changes: verify stdout, stderr, exit, output-file, and report behavior against the CLI contract and subprocess guidance, including failures.
• Report or diagnostics changes: review report assembly tests and redaction checks, metadata fields, and artifact paths.
• Schema or serialization changes: review output-schema tests and internal/core/schema tests, including supported formats and rejection of unsupported schemas.
• Changes affecting assembled output: inspect CLI parity and release fixtures.

Use the contributor guide for baseline commands. These recipes supplement, rather than duplicate, public contracts.