DotEnvy — .env Manager & Secret Scanner for VS Code

Switch, validate, encrypt and sync .env files without leaving VS Code — part of the DotSuite developer toolkit.

📥 Install from the Marketplace • 🌐 DotEnvy on DotSuite • 📝 Changelog • 🐛 Report an Issue

Contents

• Why DotEnvy
• Features
• Quick Start
• Commands
• Configuration
• Secret Scanning & .dotenvyignore
• Cloud Sync with Doppler
• Privacy & Security
• Development
• Contributors
• Part of DotSuite
• License

Why DotEnvy

• One click to switch between .env.development, .env.staging, .env.production or any custom file — no more renaming or copy-pasting.
• Catch leaked keys early with an offline secret scanner, editor warnings and a pre-commit hook.
• Keep secrets encrypted with AES-256-GCM backups, multi-user key wrapping and end-to-end encrypted Doppler sync.
• Never lose a value thanks to local history, a timeline, analytics and a session Trash Bin.
• Works in your language: English, Italian, Arabic (full RTL) and Russian.

Features

🔄 Environment Switching

Switch between .env.* files from the sidebar, the dashboard or the Command Palette. The selected file is copied to .env and the status bar shows the active environment. Map Git branches to environments to switch automatically (develop → .env.development, main → .env.production).

🔍 Offline Secret Scanner

Rule-based detection of API keys, tokens, passwords, private keys and database URLs — fully local, with no network requests.

• Known key formats for Stripe, AWS, GitHub, Slack, SendGrid, Google, OpenAI, Twilio, Mailgun, Sentry, SSH private keys and more.
• Entropy and context signals — risky variable names (DB_PASS, client_secret) and surrounding code raise or lower each result to High, Medium or Low.
• Secrets Panel with confidence filters, search and View / Move to .env / Not a Secret actions. View opens the original file and selects the complete value.
• Local corrections — "Not a Secret" and "Move to .env" are remembered for the same file, variable and value.
• Fewer false positives — import/require paths, URL fragments and file paths are not reported as Base64 secrets.
• Editor warnings in the Problems panel and a Review Secrets notification when a changed file contains findings.
• Responsive on large workspaces — at most four files scan at once and the UI stays usable.

🛡️ Git Commit Protection

A pre-commit hook blocks commits that contain secrets, validation errors or .env files. Git root discovery supports monorepos.

✅ Validation & Diff

Validate .env files for syntax errors, required variables and types (number, boolean, url or custom regex). Compare files side by side in VS Code's native diff before switching, and find the same key with different values across environments.

☁️ Doppler Cloud Sync

Connect Doppler in the browser with no CLI or manual token copying. Push and pull with end-to-end encryption, multi-file prefix routing (BACKEND_, FRONTEND_), a read-only cloud diff, and pulls that keep your comments and layout. Setup details ↓

🔐 Encryption & Backups

• Automatic backups before switching, with portable AES-256-GCM encrypted backups that restore on any device.
• Master keys in VS Code SecretStorage, and multi-user envelope encryption with per-user access and revocation.

📊 History, Timeline, Analytics & Trash Bin

Review .env changes like Git commits, roll back from history, browse the timeline, track stability metrics and restore deleted variables from the session Trash Bin.

Analytics reads local recorded history. Switching an environment or saving an .env/.env.* file creates a record; actions from before installation cannot be reconstructed. History is stored under .dotenvy/history (or history.storagePath) and includes file contents, so keep that folder out of Git. Set history.enabled: false in .dotenvy.json to stop recording, or history.trackManualEdits: false to skip editor saves.

🌐 Localization

English, Italian (it), Arabic (ar, full RTL) and Russian (ru) across every command, notification and panel. Switch languages instantly from the sidebar.

Quick Start

1. Install DotEnvy from the VS Code Marketplace, or search for "dotenvy" in the Extensions view (Ctrl+Shift+X / ⌘+Shift+X). Requires VS Code 1.90.0 or later.

2. Add environment files to your project root:

   .env.development
   .env.staging
   .env.production
   

3. Run DotEnvy: Switch Environment from the Command Palette (Ctrl+Shift+P / ⌘+Shift+P) and pick one. It is copied to .env and shown in the status bar.

Initialize a project (optional)

• Init Secure Project asks for a project name, an admin username and a password. It creates .dotenvy.lock.json (the password-wrapped project key and users) and opens .dotenvy.json. Cancelling any prompt stops setup; reinitializing replaces existing keys only after confirmation.
• Init .dotenvyignore creates a default ignore file, or opens your existing one without changing it.

With several folders open, these commands use the first workspace folder.

Commands

All commands are available from the Command Palette.

Configuration

Create .dotenvy.json in your project root:

{
  "environments": {
    "local": ".env.local",
    "qa": ".env.qa",
    "prod": ".env.production"
  },
  "gitBranchMapping": {
    "develop": "development",
    "staging": "staging",
    "main": "production"
  },
  "autoSwitchOnBranchChange": true,
  "validation": {
    "requiredVariables": ["API_KEY", "DATABASE_URL"],
    "variableTypes": {
      "PORT": "number",
      "DEBUG": "boolean",
      "API_URL": "url"
    }
  },
  "gitCommitHook": {
    "blockEnvFiles": true,
    "blockSecrets": true,
    "blockValidationErrors": true
  }
}

Secret Scanning & .dotenvyignore

Scan for Secrets checks supported source and configuration files in every open workspace folder, including .env variants, JSON files and files without an extension. Generated and dependency folders are skipped by default: node_modules, build, dist, out, coverage, htmlcov, Python environments/caches and DotEnvy's own data folders. Test files and common fixture names are skipped too. The same rules apply to automatic file watching.

Git ignore rules do not decide what is scanned, because ignored config files can still hold real credentials. Use .dotenvyignore (same syntax as .gitignore) to skip more paths, or a negation such as !test/integration.ts to include one. Each file uses the .dotenvyignore of its own workspace folder.

# .dotenvyignore

# DotEnvy's own data (always recommended)
.dotenvy/**
.dotenvy-backups/**

# Test files (often contain example secrets)
**/*.test.ts
**/*.spec.ts
tests/**

# Docs with example secrets
docs/**
README.md

# Specific files
k8s/secrets.yaml

Run DotEnvy: Init .dotenvyignore to create a default file, or right-click a file or folder in the Explorer and choose DotEnvy: Ignore this path.

Cloud Sync with Doppler

Connect in one step

Click Connect Doppler in the Environment Manager, or run DotEnvy: Connect Doppler. DotEnvy opens Doppler's sign-in page with a one-time code (use Copy Code). After you approve access, DotEnvy:

1. Uses your configured project/config, or for a fresh setup derives a lowercase project name from package.json or the folder name and uses dev.
2. Connects to that exact project, creating it if needed, without selecting a production config or replacing remote secrets.
3. Creates a read/write service token limited to that config, checks access without downloading secret values, and stores the token in VS Code SecretStorage.
4. Revokes the temporary account credential used for setup. The button then becomes Doppler and opens your project dashboard.

Connecting never uploads .env values or runs a push/pull. If setup fails or you cancel, your existing settings and token are kept; the notification names the failing step and HTTP status, and View → Output → DotEnvy shows credential-free diagnostics. All requests go directly to api.doppler.com. Sign-in uses the device authorization flow of the official Doppler CLI (compatible with v3.77.0).

Manual configuration

{
  "cloudSync": {
    "provider": "doppler",
    "project": "your-project-name",
    "config": "dev"
  }
}

Replace the example values with your Doppler project slug and a config your token can access. Project names are normalized to lowercase slugs (dots and spaces become hyphens).

• Tokens: On an authentication error, choose Set Doppler Token to store a token in SecretStorage; the legacy cloudSync.token JSON field is removed. Precedence: project SecretStorage → DOPPLER_TOKEN environment variable → legacy config field.
• HTTP 401 means the token was rejected (example, expired or revoked). HTTP 403 means it cannot access that project/config; pushing needs write access. See the Doppler service token docs.
• Encryption: Portable encryption is on by default. The first encrypted push asks for a sync passphrase (PBKDF2 + AES-256-GCM); another machine pulls with the same passphrase. DotEnvy cannot recover a lost passphrase.
• Pull merges into existing files and keeps comments, layout, multiline values and CRLF line endings. It backs up each file to a sibling .backup and adds .env*.backup to .gitignore.
• Multiple files: configure envTargets with keyPrefix, prefixes or catchAll. pushMode: "replace" removes remote keys missing locally, after confirmation.
• A missing Doppler config asks you to choose one; DotEnvy never switches environments on its own.

Privacy & Security

The secret scanner runs fully offline. Keys, code and corrections never leave your machine.

Corrections apply only to the same file, variable and complete value. A changed value or another file does not inherit them. DotEnvy: Reset Local Secret Corrections clears them.

The scanner estimates whether a value looks like a secret. It does not check whether a key is real, active or revoked, and false positives or missed secrets are possible. Moving a value to .env does not revoke it or remove it from Git history. Doppler push/pull sends environment data only to the Doppler account you configure. Please don't post live credentials or private code in issues.

Why DotAegis is no longer included

Earlier versions bundled DotAegis, a small AI model that re-scored scanner results, plus an optional upload of numeric corrections to train it. It has been removed from DotEnvy completely. A useful model needs a large set of real, labelled keys, and nobody can or should hand over real secrets to train it. The bundled model was trained on synthetic data only, so DotEnvy now relies on transparent rules instead. DotAegis continues as a separate DotSuite project.

Upgrading deletes any pending upload queue and consent state. The dotenvy.secrets.enableCommunityLearning, dotenvy.secrets.enableModelUpdates and dotenvy.secrets.enableCloudAnalysis settings no longer exist. Data an older version already sent is not erased by upgrading.

Development

git clone https://github.com/kareem2099/dotenvy.git
cd dotenvy
npm ci
npm run compile
npm test

npm test compiles, lints and runs the full suite (node test/run-all-tests.js). Offline suites block all HTTP/fetch calls. Press F5 in VS Code to launch an Extension Development Host. See CONTRIBUTING.md for the project layout and pull request process.

Contributors

Issues and pull requests are welcome — read CONTRIBUTING.md first.

Special thanks to @FaberVi for the Italian localization, language switcher, compact sidebar and Doppler multi-file sync (#2), and for the module split, portable cloud encryption, cloud pull fixes and test suites (#5).

Part of DotSuite

DotEnvy is one of the tools in DotSuite — an ecosystem of modern, privacy-focused developer tools for VS Code and Linux.

🌐 DotSuite: www.dotsuite.dev · DotEnvy page: dotsuite.dev/en/product/dotenvy

CodeTune · DotCommand · DotEnvy · DotFetch · DotReadme · DotSense · DotShare · DotScramble · DotAegis · DotGhostBoard

License

Licensed under the Apache License 2.0. The license includes the warranty terms; this README adds no guarantee of complete secret detection or credential protection.