Overview

Configuration management is one of the most error-prone aspects of deploying modern web applications. Developers routinely face cryptic startup crashes when environment variables are missing, struggle to balance configuration profiles across local development, staging, and production environments, or inadvertently leak database credentials into debug logs and terminal stack traces.

envguard extends pydantic-settings to provide opinionated, profile-aware configuration management with built-in secret masking and clear, human-readable startup validation errors.

---

Environment Profiles with Clear Precedence

Applications rarely run with identical configuration parameters in development, continuous integration, and production clusters. envguard provides structured cascading profile resolution:

1. .env (Global default baseline values)
2. .env.{profile} (Environment-specific overrides, e.g. .env.staging, .env.production)
3. .env.{profile}.local (Developer-local gitignored overrides)
4. Active process environment variables (Highest precedence, injected via Docker / Kubernetes)

The active environment profile is resolved dynamically via ENVGUARD_PROFILE (defaulting safely to development).

---

Automatic Secret Masking

Any configuration field representing a sensitive credential is automatically detected and masked in all string representations (__repr__, __str__, and logging serializations):

• Fields typed with pydantic.SecretStr
• Fields named with security indicators (*password*, *secret*, *token*, *api_key*, *dsn*)
• Explicitly annotated metadata: Field(..., json_schema_extra={"secret": True})

from envguard import BaseSettings, SecretStr

class AppConfig(BaseSettings):
    database_url: SecretStr
    stripe_api_key: SecretStr
    max_workers: int = 4

config = AppConfig()
print(config)
# AppConfig(database_url=SecretStr('**********'), stripe_api_key=SecretStr('**********'), max_workers=4)

---

Actionable Error Diagnostics

Instead of unformatted, nested Pydantic tracebacks that obscure missing variables in CI/CD deployment pipelines, envguard catches validation failures and formats a crisp diagnostic checklist:

======================================================================
CONFIG VALIDATION FAILED: 2 Missing Required Variable(s)
======================================================================
  ✗ DATABASE_URL
    - Expected Type: SecretStr (PostgreSQL DSN)
    - Description: Primary relational database connection string
    - Fix: export DATABASE_URL="postgresql://user:pass@host:5432/db"

  ✗ STRIPE_SECRET_KEY
    - Expected Type: SecretStr
    - Description: Stripe payment gateway secret key
    - Fix: Define STRIPE_SECRET_KEY in .env.production or system environment
======================================================================

---

Developer CLI Utilities

• envguard example: Automatically generates an annotated .env.example file populated with default values and documentation docstrings directly from your Pydantic settings models.
• envguard validate: Pre-flight verification tool for deployment scripts and CI workflows to validate current environment variables before launching application containers.