EnvShield 🛡️ – The Environment Contract CLI for Python & TypeScript

EnvShield turns env.schema.toml into your project's Environment Contract — one schema that generates your docs, validates every local setup, and compiles into typed, secret-masked config code for Python or TypeScript. It's your caffeine-proof way to avoid the "oops, I just leaked prod keys" nightmare.

📚 Full Documentation

Table of Contents

1. Why Secure Environment Management Matters

2. Key Features of the EnvShield CLI

3. Installation

4. The EnvShield Philosophy: Schema-First Configuration

5. CLI Commands

6. Competitor Comparison: Choosing the Right Tool

7. The Brains of the Operation: The Core Files

8. Future Roadmap: Teams & Enterprise

9. Community & Support

10. TL;DR

Why Secure Environment Management Matters

Managing .env files by copy-pasting them around like a hot potato is fun… until a secret lands in a public repo, or os.getenv("MAX_RETIRES") (typo and all) silently returns None in production. EnvShield solves the “dotenv dumpster fire” by giving you a single Environment Contract — env.schema.toml — that generates your documentation, validates every local setup, compiles into typed config code, and blocks secrets before they're ever committed. All wrapped in a workflow lazy enough for a 3 a.m. commit.

Key Features of the EnvShield CLI

• One Environment Contract – env.schema.toml becomes the single source of truth every other command reads from.

• Typed Config Generation – envshield generate compiles your schema into real, importable pydantic-settings (Python) or zod (TypeScript) code — secrets are masked by default (SecretStr / Secret<T>), everything else is a validated, correctly-typed value instead of a raw string.

• Open-Source Secret Scanner – Detects API keys, private keys, and other credentials before you push.

• Local Development Workflow – Automatic .env.example syncing and onboarding that even future-you will thank you for.

• Git Pre-commit Hook – Blocks secret leaks faster than you can say git push --force.

• Configuration as Code – Your environment config is version-controlled and documented like real code.

(Translation: EnvShield is that overprotective friend who checks the door lock five times so you can sleep.)

Installation

Requires Python 3.10+.

pip install envshield
envshield --help

Done. Your project is now 72 % less combustible.

The EnvShield Philosophy: Schema-First Configuration

EnvShield's power comes from a simple idea: your configuration should be treated like code. It introduces a single source of truth, the env.schema.toml file.

This file is a "configuration contract" that explicitly defines every environment variable your project needs. By defining your variables here, you get:

• Automated Documentation: Your .env.example is always perfectly in sync with your schema.
• Ironclad Validation: Catch typos and missing variables before you even run your app.
• Proactive Security: A built-in scanner and Git hook prevent secrets from ever being committed.

CLI Commands

Command	Purpose	Demo
envshield init	Auto-detects framework, creates env.schema.toml, installs the Git hook.
envshield scan	Scans files or staged commits for secrets.
envshield install-hook	Manually install or update the Git pre-commit hook.	For when you skipped step one because YOLO.
envshield check <file>	Validates a local .env file against the schema.
envshield schema sync	Regenerates .env.example from the schema.
envshield setup	Interactive onboarding to create a local env.
envshield doctor	Runs a full health check (and can auto-fix).
envshield import <file>	Intelligently converts an existing .env file into a new env.schema.toml.	The fastest way to adopt EnvShield for an existing project.
envshield generate	Compiles your schema into a typed, validated config module — pydantic-settings (Python) or zod (TypeScript), auto-detected or set via --lang.	Turns the contract into the actual code your app imports.

Competitor Comparison: Choosing the Right Tool

A scanner is a smoke detector. A cloud vault is an off-site bank. EnvShield is the fireproof, self-organizing house you should have been living in all along. It provides the complete local workflow that developers need to prevent secret leaks in the first place.

Think of scanners as smoke detectors and cloud vaults as off-site banks. EnvShield is the fire-proof, self-organizing house you should have been living in all along.

The Brains of the Operation: The Core Files

envshield is managed by two simple files you commit to your repository.

• env.schema.toml: The source of truth. This is where you define every variable your project needs.

    # env.schema.toml

    [DATABASE_URL]
    description = "The full connection string for the PostgreSQL database."
    secret = true # Marks this as sensitive

    [LOG_LEVEL]
    description = "Controls the application's log verbosity."
    secret = false
    defaultValue = "info" # Provides a fallback

• envshield.yml: The workflow config. In Phase 1, it's very simple and mainly points to your schema and defines scanner exclusions.

Future Roadmap: Teams & Enterprise✨

Phase 1 is the free, powerful "Local Guardian." But the journey doesn't end there. Upcoming paid tiers will turn envshield into a complete collaboration and automation platform.

Phase 2: The Team Collaborator (Paid Tier)

• envshield use <profile>: Instantly switch your entire project's configuration between different environments (e.g., local, staging).

• envshield onboard <profile>: A supercharged setup that can also run scripts like docker compose up and database migrations for a true one-command setup.

• envshield share: Securely share a secret with a teammate via an encrypted, one-time-use link.

• envshield docs: Generate beautiful Markdown or HTML documentation from your schema.

Phase 3: The Enterprise-Grade System (Paid Tier)

• envshield login, pull, push: Full integration with a centralized, cloud-based secret vault.

• envshield export: Securely inject secrets into your CI/CD pipelines for automated deployments.

• Audit Logs & RBAC: A complete, compliant, and auditable history of all secret access and team permissions, managed through a web dashboard.

Community & Support

Got questions? Have a brilliant idea? Come hang out with us!

• 🤔 Ask a question on GitHub Discussions:Discussions

Or, Follow us on our socials:

🌍 Community & Links

• 🌐 Website: envshield.dev
• 🐙 GitHub: rabbilyasar/envshield
• 🐍 PyPI: EnvShield on PyPI
• 🤔 GitHub Discussions: GitHub Discussions
• 💬 Join our Discord:@discord

Contributing (Don't Be Shy)

Spotted a bug? Think our jokes are terrible? We want to hear it all. Check out CONTRIBUTING.md to get started.

TL;DR

EnvShield = one Environment Contract that gives you docs, validation, secret scanning, and typed Python/TypeScript config code — plus just enough sarcasm to keep you awake. Stop leaking secrets. Start shipping securely.