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, selected overlay, credential reference, and CLI mapping as applicable. Preserve the precedence 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.

The version route uses ReleaseKit's public buildinfo.Version() accessor and stays independent of application runtime assembly. Preserve its behavior from the CLI contract when changing the command; the adoption decision is recorded in ADR 0001.

Validating Examples

Keep complete copyable files in examples and link to them from their canonical contract documentation. Keep them valid and secret-free. Run the commands in the example guide from each project's directory. internal/cli/examples_integration_test.go exercises the maintained projects with a controlled provider, and the preview fixture can be prepared without inference. Review automatic companion sources and overlays in their actual project directories. Keep service credentials synthetic in tests.

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 controlled HTTP subprocess workflows and retained report/artifact assertions.

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