Skip to content

Config

provide.foundation.cli.commands.config

Configuration management CLI commands.

This module provides CLI commands for inspecting and managing Foundation configuration schemas.

Functions

schema_command 

schema_command(
    format: str,
    category: str | None,
    env_only: bool,
    show_sensitive: bool,
    output: str | None,
) -> None

Display all available configuration options and their schemas.

This command introspects all registered configuration classes and displays their schemas, including environment variable mappings, types, defaults, and descriptions.

Examples:

# Display all configuration in human-readable format
foundation config schema

# Show only environment variables in JSON format
foundation config schema --env-only --format json

# Filter by category and output to file
foundation config schema --category logger --output config.md --format markdown

# Include sensitive fields (they will be masked)
foundation config schema --show-sensitive
Source code in provide/foundation/cli/commands/config.py 
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
@config_group.command("schema")
@click.option(
    "--format",
    "-f",
    type=click.Choice(["human", "json", "yaml", "markdown"]),
    default="human",
    help="Output format for schema",
)
@click.option(
    "--category",
    "-c",
    help="Filter by category (e.g., logger, transport)",
)
@click.option(
    "--env-only",
    is_flag=True,
    help="Show only environment variables",
)
@click.option(
    "--show-sensitive",
    is_flag=True,
    help="Include sensitive fields (masked by default)",
)
@click.option(
    "--output",
    "-o",
    type=click.Path(),
    help="Output to file instead of stdout",
)
@requires_click
@with_cleanup
def schema_command(
    format: str,
    category: str | None,
    env_only: bool,
    show_sensitive: bool,
    output: str | None,
) -> None:
    """Display all available configuration options and their schemas.

    This command introspects all registered configuration classes and displays
    their schemas, including environment variable mappings, types, defaults,
    and descriptions.

    Examples:

        # Display all configuration in human-readable format
        foundation config schema

        # Show only environment variables in JSON format
        foundation config schema --env-only --format json

        # Filter by category and output to file
        foundation config schema --category logger --output config.md --format markdown

        # Include sensitive fields (they will be masked)
        foundation config schema --show-sensitive

    """
    try:
        # Import here to avoid circular dependencies
        from provide.foundation.config.discovery import get_consolidated_schema
        from provide.foundation.config.formatters import get_formatter

        # Get consolidated schema
        schema = get_consolidated_schema()

        # Check if any schemas found
        if not schema.schemas:
            perr("No configuration schemas found. Ensure Foundation is initialized.")
            exit_error("No schemas available", code=1)

        # Get formatter
        try:
            formatter = get_formatter(format)
        except ValueError as e:
            perr(f"Invalid format: {e}")
            exit_error("Invalid format", code=1)

        # Format output
        result = formatter.format(
            schema,
            env_only=env_only,
            show_sensitive=show_sensitive,
            category=category,
        )

        # Output result
        if output:
            from pathlib import Path

            try:
                Path(output).write_text(result)
                pout(f"Schema written to {output}")
            except OSError as e:
                perr(f"Failed to write to file: {e}")
                exit_error("File write failed", code=1)
        else:
            pout(result)

    except Exception as e:
        perr(f"Failed to generate schema: {e}")
        exit_error("Schema generation failed", code=1)