Documentation

🏗️ init

The "zero-to-hero" command. Run this first in a new project to scaffold a complete, best-practice configuration foundation.

What it does:

• Intelligently inspects your project to detect the framework (e.g., Next.js, Django).
• Creates an `env.schema.toml` file with smart defaults for that framework.
• Creates a simple `envshield.yml` configuration file.
• Safely updates your `.gitignore` file with necessary patterns.
• Automatically installs the Git pre-commit hook for proactive security.

Flags:

--force or -f: Allows `init` to overwrite existing EnvShield files. It will always ask for a final confirmation before proceeding.

Use Case

You're starting a new Django project. You run `envshield init`. The tool detects Django, creates a schema with `SECRET_KEY` and `DATABASE_URL`, updates your `.gitignore`, and installs the security hook. Your project is set up for success in one command.

🚚 import

The "get started yesterday" command. This is the fastest way to adopt EnvShield for an existing project with a large, messy `.env` file.

What it does:

• Reads an existing `.env` file (like `.env.production`).
• Intelligently analyzes each variable's key and value.
• Automatically marks known secrets (API keys, tokens) using its built-in scanner logic.
• Suggests default values for common variables (like `DEBUG` or `PORT`).
• Generates a complete `env.schema.toml` file for you.

Arguments & Flags:

• <file>: (Required) The path to the `.env` file you want to import.
• --output or -o: Specify a different output path for the schema file (default: `env.schema.toml`).
• --force or -f: Allows `import` to overwrite an existing schema file.
• --interactive: Walks you through each variable one by one, letting you confirm if it's a secret and if you want to set a default value.

Use Case

You want to adopt EnvShield for a 2-year-old project. You run the command:

envshield import .env --interactive

The tool guides you through all 50 variables, correctly guessing 45 of them, and generates a perfect schema file in two minutes instead of an hour of manual work.

💪 scan

Your project's personal bodyguard. It scans files for hardcoded secrets and undeclared environment variables used in your code.

Arguments & Flags:

• [PATHS]...: The specific files or directories to scan. If you don't provide a path, it scans the current directory.
• --staged: Scans only the files you've staged for your next Git commit. This is the heart of the pre-commit hook.
• --config <file>: Use a different `envshield.yml` for this specific scan.
• --exclude <pattern>: A glob pattern to exclude from this specific scan. Can be used multiple times.

Use Case

Your pre-commit hook is blocking a commit because of a secret in a test file. You realize you forgot to add an exclusion rule. You can add it to `envshield.yml` to fix it permanently, or use a one-off command to bypass it for now:

git commit -m "My commit" --no-verify # Bypass the hook for now
envshield scan . --exclude "**/tests/*"

🛑 install-hook

Manually installs the Git pre-commit hook if you skipped it during `init` or if it was removed.

What it does:

Creates (or overwrites) a `pre-commit` script in your `.git/hooks/` directory that runs `envshield scan --staged`.

Use Case

You've added `envshield` to a project that already had a different pre-commit hook. After you manually merge the two scripts, you can run `envshield install-hook --force` to create the final, combined hook.

📚 schema

The `schema` command is a subcommand with one action: `sync`. It's your primary tool for keeping your project's documentation (`.env.example`) perfectly in sync with your schema.

Usage

envshield schema sync

Use Case

You add a new `REDIS_URL` variable to your `env.schema.toml`. Before you commit, you run `envshield schema sync`. The `.env.example` is instantly and correctly updated with the new variable and its description, ready to be committed.

✅ check

The "is it plugged in?" command for your local setup. It validates a local environment file against the official contract in `env.schema.toml`.

What it does:

It reports missing variables (that don't have a default) and extra variables that are not in the schema, helping you find configuration errors before they cause runtime bugs.

Use Case

Your app fails to start after a teammate's PR. You run the command:

envshield check .env.local

The tool reports `Missing in Local: NEW_SERVICE_API_KEY`, instantly telling you what's wrong.

🪄 setup

A taste of the automated onboarding magic. This is the perfect command for getting started on a project.

What it does:

It reads your `.env.example`, finds any variables that are empty, and interactively prompts you for their values. It then generates your first local `.env` file.

Use Case

You just cloned a new project. You run `envshield setup`. The tool asks you for the `DATABASE_URL` and `STRIPE_API_KEY`, then generates your fully-populated `.env` file. You are ready to run the project in minutes.

🩺 doctor

The "turn it off and on again" command for your entire configuration. It runs a comprehensive suite of health checks on your project's `envshield` setup.

What it does:

• Checks that your `envshield.yml` and `env.schema.toml` files exist and are valid.
• Validates your local `.env` file against the schema.
• Ensures your `.env.example` file is in sync with the schema.
• Verifies that the security hook is installed and active.

Flags:

--fix: The magic wand. If the doctor finds a problem, it will interactively ask you if you want to fix it automatically.

Use Case

Something just feels wrong with your setup. You run `envshield doctor`. It reports that your `.env.example` is out of date and the Git hook is missing. You run `envshield doctor --fix`, answer "Yes" to both prompts, and the tool fixes everything for you.

🧬 generate

The command that turns your contract into code. It compiles `env.schema.toml` into a typed, validated config module — no more raw `os.getenv()` / `process.env` calls scattered through your codebase, and no more secrets that can accidentally end up in a log line.

What it does:

• Renders every variable in your schema into a real, importable module: `pydantic-settings` for Python, or a `zod`-validated module for TypeScript.
• Infers each variable's type (`str`, `int`, `bool` / `string`, `number`, `boolean`) from its `defaultValue`. Variables with no default become required fields — the module raises a validation error at import time if they're missing.
• Wraps every `secret = true` variable in a masked type (`SecretStr` in Python, a local `Secret<T>` wrapper in TypeScript) so it can't accidentally leak via a `print()`, `console.log`, `JSON.stringify`, or stack trace. You call `.get_secret_value()` / `.value` explicitly to read it.

Arguments & Flags:

• [output_file]: Where to write the generated module. Defaults to `config.py` or `config.ts` depending on the resolved language.
• --lang or -l: `python` or `typescript`. If omitted, EnvShield auto-detects from your project the same way `init` does — Next.js, Vite, and Node.js projects default to TypeScript; everything else defaults to Python.
• --force or -f: Allows `generate` to overwrite an existing output file.

Use Case

Your Next.js app currently reads `process.env.STRIPE_SECRET_KEY` directly in six different files, with no validation that it's actually set. You run:

envshield generate --lang typescript

EnvShield writes `config.ts` with a `zod` schema built from your contract. You replace the six direct `process.env` reads with `import { env } from './config'` — now a missing or malformed variable fails loudly at startup instead of silently at runtime, and `env.STRIPE_SECRET_KEY` prints as `**********` anywhere it's accidentally logged.