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.

Already have more than one service in this repo? `init` bootstraps a single schema — for a multi-service project, use `envshield service discover` instead.

🚚 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.

🔭 service

The fast path for multi-service projects. A subcommand with three actions: discover, add, and list.

discover — What it does:

• Scans your repo for directories that look like independent services — a real dotenv file (any .env.* name, not just .env), or a recognizable Python config module.
• Skips a directory that only has a generic project marker (pyproject.toml, package.json) with no actual config in it — a shared library sitting next to your real services won't get mistaken for one.
• Shows you what it found and asks before writing anything.
• On confirmation, registers each service in envshield.yml and seeds its schema straight from its real, current config — the same logic as import.
• Safe to run again later: already-registered services are never re-suggested or touched. It bootstraps a fresh setup from nothing, or extends an existing one with whatever's new.

$ envshield service discover

                     Discovered Services
┏━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name   ┃ Directory      ┃ Format ┃ Config File           ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ api    │ services/api   │ dotenv │ (default .env)        │
│ web    │ services/web   │ dotenv │ (default .env)        │
└────────┴────────────────┴────────┴───────────────────────┘
? Add these services to envshield.yml? (api, web pre-selected) Yes
✓ Registered api → services/api/env.schema.toml
✓ Registered web → services/web/env.schema.toml

add & list

envshield service add <name> <directory> registers one service by hand — useful when you'd rather be explicit than rely on detection, with --local-file, --description, and --import <file> to seed its schema in the same step. envshield service list prints every service currently configured.

Use Case

You're adopting EnvShield in an existing Turborepo with five apps. Instead of hand-writing envshield.yml and running import five times, one command finds them all, and one confirmation seeds all five schemas from their real, current .env files.

💪 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 variables missing entirely, variables declared but still left blank (e.g. a required secret checked in as an empty placeholder), and extra variables that aren't in the schema — helping you find configuration errors before they cause runtime bugs, not after.

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 looks at whatever you already have — your real local file if one exists, or `.env.example` as a template if not — and prompts you only for variables that are still blank or missing, showing each one's description and masking input for secrets. On a multi-service project, running it with no `--service` asks which one (or All services, walking through each service's wizard in turn). If your local config isn't a dotenv file — e.g. a Python module — it patches just the missing values into it in place, instead of overwriting the 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.