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, --example-file, --description / -d, --schema (a non-default schema path), and --import <file> to seed its schema in the same step. --deployment-manifest registers a docker-compose file or Kubernetes manifest to validate automatically (auto-detected if omitted — see Deployment Manifests), and --container names which service/container in it is this one, if it isn't named the same. 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 — or, these days, a docker-compose file or a Kubernetes manifest — 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), variables present but not matching their declared `type`/`enum`/`pattern`, and extra variables that aren't in the schema — helping you find configuration errors before they cause runtime bugs, not after. When you don't pass a file argument, it also checks the registered deployment manifest (if any) in the same run — see Deployment Manifests.

Arguments & Flags:

• [file]: The file to validate. Omit it to check the project's/service's default local file (and its registered deployment manifest, if any).
• --service / -s: On a multi-service project, which service's schema to check against.
• --container: For a docker-compose or Kubernetes manifest declaring more than one service/container, which one to check. Tried against `--service`'s name automatically first.

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. Add it as a CI step (see the README's Maintaining EnvShield section) and this becomes a pull-request check, not a post-deploy surprise.

🪄 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, including type/enum/pattern constraints, not just presence.
• Ensures your `.env.example` file is in sync with the schema.
• Verifies that the security hook is installed where Git will actually run it (respecting a configured `core.hooksPath`, e.g. Husky).
• If a deployment manifest is registered for this project/service, validates it too — this check is only shown at all when one actually is.

Flags:

--fix: If the doctor finds a problem, it interactively asks if you want to fix it — re-running `init`, regenerating `.env.example`, installing the hook, or, for missing/blank/invalid local values, running the same `setup` wizard used for onboarding (which fixes exactly what's wrong and leaves everything else untouched).

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.
• Types each field from its schema's explicit `type`/`enum`/`pattern` when set (`AnyUrl`, `EmailStr`, `Literal[...]`, a regex-constrained string) — or, if none is set, infers `int`/ `bool`/`string` from the shape of `defaultValue`, same as always. 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.