Documentation

Complete guide to installing, configuring, and using envcrypt to secure your environment variables.

Installation

envcrypt requires Node.js 18 or higher. You can install it globally or as a project dependency.

Global Installation (Recommended)

# Install globally to use the CLI anywhere
npm install -g envcrypt

# Verify installation
envcrypt --version

Project Installation

# Install as a project dependency
npm install envcrypt

# Or with yarn
yarn add envcrypt

# Or with pnpm
pnpm add envcrypt

Quick Start

Get up and running with envcrypt in under 60 seconds.

1. Initialize your environment:

   envcrypt init

   Follow the interactive prompts to set up your project name, framework, and variables.

2. Install the runtime in your project:

   npm install envcrypt

3. Add the decrypt line to your entry file:

   import { decryptToEnv } from "envcrypt";
   await decryptToEnv();
   
   // Your app code here — process.env is populated

4. Run your app securely:

   envcrypt run npm start

Your First Encrypt

Let's walk through a complete example with an Express.js application.

Step 1: Initialize

$ envcrypt init

🔐 envcrypt initialization
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

? Project name: my-api
? Framework: Express.js
? Generate JWT secret? Yes
? Generate session secret? Yes
? Database port (detected free: 5433): 5433
? API port (detected free: 3001): 3001

✓ Generated cryptographically secure secrets
✓ Detected safe ports: 5433, 3001
✓ Encrypted 8 variables into .env.enc

Step 2: Integrate

Create or update your server.js:

import { decryptToEnv } from "envcrypt";
await decryptToEnv();

import express from "express";
const app = express();

const port = process.env.API_PORT || 3000;

app.get("/", (req, res) => {
  res.json({ message: "API secured with envcrypt" });
});

app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

Step 3: Run

$ envcrypt run node server.js
Enter env-lock password: ********
✓ Environment decrypted
▶ Running: node server.js

Server running on port 3001
✓ Process exited with code 0

envcrypt init

The init command interactively guides you through setting up a new encrypted environment.

Options

Presets

Presets pre-configure common environment variables for popular frameworks:

# Node.js + JWT + PostgreSQL
envcrypt init --preset node-jwt-postgres

# Node.js + MongoDB
envcrypt init --preset node-mongodb

# Python Django
envcrypt init --preset python-django

# Go backend
envcrypt init --preset go-standard

# Vanilla JavaScript
envcrypt init --preset vanilla-js

What Gets Created

your-project/
├── .env.enc              # Encrypted environment (safe to commit)
├── .envcrypt/
│   ├── config.json       # Project schema and metadata
│   └── audit.log         # Decrypt event log
└── .gitignore            # .env files ignored automatically

envcrypt run

Decrypts your environment variables into memory and executes the specified command.

# Run a Node.js script
envcrypt run node server.js

# Run npm scripts
envcrypt run npm start
envcrypt run npm run dev

# Run with arguments
envcrypt run node --inspect server.js

envcrypt doctor

Health check your environment setup. Verifies:

• .env.enc file exists and is valid
• Configuration is correct
• .gitignore properly excludes .env files
• No plaintext .env files exist
• Node.js version is compatible

$ envcrypt doctor

🩺 envcrypt Doctor
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ .env.enc file          Found (2.34 KB)
✓ Configuration          Project: my-api, Version: 1.0.0
✓ .gitignore             .env ignored, .env.enc not ignored (correct)
✓ Node.js version        v20.11.0 (>= 18.0.0)
✓ Plaintext .env files   None found

✅ All checks passed! Your environment is secure.

Encryption Protocol

envcrypt uses industry-standard encryption to protect your secrets.

Algorithm Details

File Format

[4 bytes]   Magic: "ENVL"
[1 byte]    Version: 0x01
[32 bytes]  HMAC-SHA256 of header
[16 bytes]  Argon2id salt
[12 bytes]  AES-GCM IV
[N bytes]   Ciphertext (encrypted JSON)
[16 bytes]  AES-GCM auth tag

Memory Safety

envcrypt implements multiple layers of memory protection:

• Auto-shred: Buffers are overwritten with zeros, ones, and random data before being freed
• Environment cleanup: All decrypted variables are removed from process.env on exit
• Child process isolation: Secrets are passed to child processes, then wiped from parent memory
• mlock (best-effort): Attempts to pin decrypted buffers to RAM to prevent swapping to disk

Best Practices

DO

• ✅ Commit .env.enc to version control
• ✅ Use strong, unique master passwords (12+ characters)
• ✅ Run envcrypt doctor regularly
• ✅ Use envcrypt run for production deployments
• ✅ Rotate secrets periodically with envcrypt rotate

DON'T

• ❌ Never commit plaintext .env files
• ❌ Don't share your master password in Slack, email, or chat
• ❌ Don't use the same password across multiple projects
• ❌ Don't store .env.enc backups without encryption

decryptToEnv()

The main API for programmatic decryption in your application.

Signature

async function decryptToEnv(options?: {
  path?: string;    // Path to .env.enc (default: './.env.enc')
  password?: string; // Master password (optional, will prompt if not provided)
}): Promise<Record<string, string>>

Example

import { decryptToEnv } from "envcrypt";

// Simple usage — prompts for password
await decryptToEnv();

// With options
await decryptToEnv({
  path: "./config/.env.enc",
  password: process.env.ENVCRYPT_PASSWORD
});

// Returns decrypted variables
const env = await decryptToEnv();
console.log(env.JWT_SECRET);

Programmatic Usage

You can also use envcrypt's internal modules directly:

import { encrypt, decrypt } from "envcrypt/src/crypto/cipher.js";
import { generateSecret } from "envcrypt/src/crypto/secrets.js";

// Generate a secure secret
const secret = generateSecret(64); // 512-bit JWT secret

// Encrypt environment variables
const envVars = { API_KEY: "secret123", PORT: "3000" };
const encrypted = await encrypt(envVars, "my-password");

// Decrypt
const decrypted = await decrypt(encrypted, "my-password");
console.log(decrypted.API_KEY); // "secret123"