← Back to Main Site

Documentation

🚀 Quick Start Guide

Go from a chaotic environment to a secure, documented, and validated setup in less than 5 minutes. This guide will walk you through the essential workflow.

1. Install EnvShield

You'll need Python 3.10 or newer. Install EnvShield directly from PyPI.

Terminal
pip install envshield

2. Initialize Your Project (Two Paths)

Choose the path that fits your project.

Option A: For New Projects 
# This scaffolds a new config, schema, and git hook
envshield init
Option B: For Existing Projects 
# This intelligently imports your existing .env file
envshield import .env.production

3. Curate Your Schema

Open the newly created `env.schema.toml`. This is your new single source of truth. Review the variables, add descriptions, and define which ones are secrets. This is the only file you'll need to maintain.

env.schema.toml 
[DATABASE_URL]
description = "The full connection string for the database."
secret = true

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

4. Sync and Setup

Generate your `.env.example` file and then interactively create your local `.env` file or you can create it as `.env.local`. The default will create it as `.env`.

Terminal
# Create the .env.example from your schema
envshield schema sync

# Interactively create your local env file
envshield setup <file_name>

5. You're All Set!

Your environment is now secure and documented. The Git hook is active, and your configuration is guaranteed to be in sync with your schema. Go build something amazing!

💡 Core Concepts

Understanding these two concepts is key to mastering the schema-first workflow.

  • The Schema (`env.schema.toml`): This file is the **contract** for your configuration. It's the undisputed source of truth, defining every variable your project needs, what it does, whether it's a secret, and if it has a default value. It lives in your repository and is version-controlled like the rest of your code.
  • The Example File (`.env.example`): This file is the **human-readable documentation**. It's a build artifact that is automatically generated from your schema via the `schema sync` command. You never edit this file by hand; you commit it so that anyone browsing your repository can quickly understand the configuration requirements without needing the tool installed.

📖 A-to-Z Command Reference

🏗️ 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:

Terminal
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:

Terminal
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

Terminal
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:

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

⚙️ The `env.schema.toml` File

This file is the heart of your configuration. It's a TOML file where you define every environment variable your project needs. Here's a breakdown of the keys for a variable:

env.schema.toml
[DATABASE_URL]
# (Required) A human-readable explanation of what this variable is for.
# This is used to generate comments in your .env.example file.
description = "The full connection string for the PostgreSQL database."

# (Required) A boolean that marks the variable as sensitive.
# This will be used by future commands like `onboard` and `audit`.
secret = true

# (Optional) A default value for the variable.
# If a variable has a defaultValue, `envshield check` will not report it as missing.
# It will also be pre-filled in your .env.example file.
defaultValue = "postgres://user:pass@localhost:5432/mydb"

⚙️ The `envshield.yml` File

This file controls the workflow and settings for the EnvShield tool itself.

envshield.yml
# The name of your project (used for display purposes).
project_name: my-project

# The version of the config file format.
version: 2.0

# (Required) The path to your schema file.
schema: env.schema.toml

# Global settings for the secret scanner.
secret_scanning:
  # A list of file patterns to ignore during scans (e.g., test files).
  exclude_files:
    - "**/tests/*"
    - "**/test/*"

🛣️ Roadmap: The Future is Bright

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.

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.