secure-env CLI Reference: encrypt and decrypt Commands

Full reference for the secure-env CLI: encrypt and decrypt subcommands, argument defaults, environment variables, exit codes, and usage without npx.

The secure-env binary ships with @vernonthedev/encryptd and provides two subcommands: encrypt converts a plaintext .env file into an encrypted .env.enc JSON file, and decrypt reverses that process, printing the plaintext to stdout. Both commands require the passphrase to be available in the ENV_PASSPHRASE environment variable before they run.

---

secure-env encrypt

The encrypt subcommand reads the plaintext input file, encrypts it with AES-256-GCM using the key derived from ENV_PASSPHRASE, 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

inputFile · string · default: ".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 · default: ".env.enc"

Path where the encrypted JSON file will be written. The file is 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 exits immediately with an error if this variable is not set.

Examples

Default paths (.env → .env.enc)

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

# In package.json:
# "scripts": { "encrypt": "secure-env encrypt" }

ENV_PASSPHRASE="s3cr3t" npm run encrypt

---

secure-env decrypt

The decrypt subcommand 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.

Syntax

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

Arguments

inputFile · string · default: ".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

Default path (.env.enc)

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

The decrypt command prints decrypted content to stdout only it does not write a file or mutate process.env. If you need the env vars loaded into a running Node.js process, use the config() library function instead.

---

Exit behavior

The CLI exits with a non-zero status code 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, check 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 through your package manager’s exec command.

pnpm exec

ENV_PASSPHRASE="s3cr3t" pnpm exec secure-env encrypt

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

You can also wire encrypt and decrypt up as npm scripts to avoid typing the full binary path every time:

package.json

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