Encrypting and Decrypting .env Files with the secure-env CLI

The secure-env binary ships with @vernonthedev/encryptd and exposes two subcommands: encrypt converts a plaintext .env file into an encrypted .env.enc JSON file, and decrypt reverses that process and prints the recovered plaintext to stdout. Both commands require the ENV_PASSPHRASE environment variable to be set before they run the CLI throws immediately if it is missing.

`secure-env encrypt`

The encrypt command reads the plaintext input file, encrypts it with AES-256-GCM using a key derived from ENV_PASSPHRASE via PBKDF2-HMAC-SHA256, and writes the resulting EnvPayload JSON to the output file. A success message is printed to stdout on completion.

Syntax

ENV_PASSPHRASE="<passphrase>" npx secure-env encrypt [inputFile] [outputFile]

Arguments

Argument	Type	Default	Description
`inputFile`	`string`	`".env"`	Path to the plaintext `.env` file to encrypt. Resolved relative to the current working directory. The file must exist or the command exits with an error.
`outputFile`	`string`	`".env.enc"`	Path where the encrypted JSON file will be written. Created or overwritten. Resolved relative to the current working directory.

Environment variables

Variable	Required	Description
`ENV_PASSPHRASE`	Yes	Passphrase used to derive the AES-256-GCM encryption key via PBKDF2-HMAC-SHA256. The command throws immediately if this variable is not set.

Examples

ENV_PASSPHRASE="my-secret-passphrase" npx secure-env encrypt
# Encrypted .env -> .env.enc

ENV_PASSPHRASE="s3cr3t" npx secure-env encrypt .env.production .env.production.enc
# Encrypted .env.production -> .env.production.enc

`secure-env decrypt`

The decrypt command reads the encrypted JSON file produced by secure-env encrypt, decrypts it using ENV_PASSPHRASE, and prints the recovered plaintext to stdout. Nothing is written to disk and process.env is not mutated.

The decrypt command is a read-only operation. It prints decrypted content to stdout only it does not write a file to disk or load variables into process.env. To load decrypted variables into a running Node.js process, use the config() library function instead.

Syntax

ENV_PASSPHRASE="<passphrase>" npx secure-env decrypt [inputFile]

Arguments

Argument	Type	Default	Description
`inputFile`	`string`	`".env.enc"`	Path to the encrypted `.env.enc` file to decrypt. Must be valid JSON matching the `EnvPayload` schema.

Environment variables

Variable	Required	Description
`ENV_PASSPHRASE`	Yes	Must exactly match the passphrase used during encryption.

Examples

ENV_PASSPHRASE="my-secret-passphrase" npx secure-env decrypt
# DATABASE_URL=postgres://localhost/mydb
# API_KEY=abc123

ENV_PASSPHRASE="s3cr3t" npx secure-env decrypt .env.production.enc

ENV_PASSPHRASE="s3cr3t" npx secure-env decrypt > .env.recovered

Exit behavior

The CLI exits with a non-zero status code (thrown Error) in the following situations:

Condition	Error message
`ENV_PASSPHRASE` not set	`[SrcIndex] Set ENV_PASSPHRASE env var.`
Input file does not exist	`[SrcIndex] <inputFile> not found.`
Decryption fails (wrong passphrase or tampered file)	`[RustLib] Decryption failed. Wrong key or tampered file.`
Encrypted file is not valid JSON	Standard `JSON.parse` error

If you receive [RustLib] Decryption failed, verify that ENV_PASSPHRASE is set to exactly the same value that was used when the file was encrypted including case and any special characters. The error is intentionally non-specific: the CLI cannot distinguish between a wrong passphrase and a tampered file.

Usage without `npx`

If you install @vernonthedev/encryptd as a local dev dependency, the secure-env binary is available inside node_modules/.bin/. You can invoke it directly or register it as an npm script to avoid typing the full path every time.

pnpm exec
Direct binary path
npm scripts

ENV_PASSPHRASE="s3cr3t" pnpm exec secure-env encrypt
ENV_PASSPHRASE="s3cr3t" pnpm exec secure-env decrypt

ENV_PASSPHRASE="s3cr3t" ./node_modules/.bin/secure-env encrypt
ENV_PASSPHRASE="s3cr3t" ./node_modules/.bin/secure-env decrypt

Add the commands to your package.json so you can run them without specifying the binary path:

package.json

{
  "scripts": {
    "encrypt": "secure-env encrypt",
    "decrypt": "secure-env decrypt"
  }
}

Then invoke them with:

ENV_PASSPHRASE="s3cr3t" npm run encrypt
ENV_PASSPHRASE="s3cr3t" npm run decrypt

​secure-env encrypt

​Syntax

​Arguments

​Environment variables

​Examples

​secure-env decrypt

​Syntax

​Arguments

​Environment variables

​Examples

​Exit behavior

​Usage without npx

`secure-env encrypt`

Syntax

Arguments

Environment variables

Examples

`secure-env decrypt`

Syntax

Arguments

Environment variables

Examples

Exit behavior

Usage without `npx`