encryptd FAQ: Passphrases, Platforms, and Configuration

Is it safe to commit `.env.enc` to version control?

Yes. The .env.enc file is encrypted with AES-256-GCM, a widely trusted authenticated encryption algorithm. Without the correct passphrase, the ciphertext is computationally unreadable.Follow these rules to keep your secrets safe:

Commit .env.enc — this is the intended workflow.
Never commit the original .env file or your passphrase.
Add .env to your .gitignore to prevent accidental commits.

.gitignore

.env
.env.*
!.env.enc
!.env.*.enc

The security guarantee only holds as long as your passphrase remains secret. Rotate the passphrase immediately if you suspect it has been exposed.

What happens if the same `.env` is encrypted twice?

The resulting ciphertext will be different each time, even if the input file and passphrase are identical. encryptd generates a fresh random salt and nonce (IV) on every encryption run, so no two .env.enc files will ever be the same.Both files will decrypt to the same plaintext content when the correct passphrase is provided. This is expected and correct behaviour.

Can I use multiple encrypted files for different environments?

Yes. Specify custom input and output file paths when encrypting:

Encrypt environment-specific files

npx secure-env encrypt .env.staging .env.staging.enc
npx secure-env encrypt .env.prod    .env.prod.enc

Then load the appropriate file at runtime using the path option:

Load by environment

import { config } from '@vernonthedev/encryptd';

config({ path: '.env.staging.enc' });

Use a NODE_ENV check or a dedicated environment variable to select the correct .enc file automatically in your application bootstrap code.

Does `config()` overwrite existing `process.env` variables?

No — by default, config() will not overwrite a key that already exists in process.env. This preserves values injected by your shell, Docker, or deployment environment, which typically take precedence over file-based configuration.If you need the values in the encrypted file to take precedence, set the override option to true:

config() with override

import { config } from '@vernonthedev/encryptd';

config({ override: true });

Do I need Rust installed to use encryptd?

No. encryptd ships prebuilt native binaries for all supported platforms. When you run npm install, the correct binary for your operating system and architecture is downloaded automatically — no Rust toolchain required.

What Node.js version is required?

Node.js 18 or higher is recommended. Older versions may work but are not officially tested or supported.

Always use an actively maintained Node.js LTS release in production. Check the Node.js release schedule for current LTS versions.

What if my platform isn't in the supported list?

encryptd currently provides prebuilt binaries for the following platforms:

OS	Architecture	libc
macOS	ARM64 (Apple Silicon)	—
macOS	x64 (Intel)	—
Linux	x64	GNU (`glibc`)
Windows	x64	—

If your platform is not listed — for example, Alpine Linux (musl), Linux ARM64, or 32-bit systems — encryptd is not currently supported there. Running inside a Docker container based on a glibc Linux distribution (such as Debian or Ubuntu) is the recommended workaround for most CI and server environments.Watch the project repository for updates if support for your platform is important to you.

How do I rotate the passphrase?

Rotating the passphrase is a two-step process: decrypt with the old passphrase, then re-encrypt with the new one.

Rotate passphrase

# Step 1: Decrypt using the old passphrase
ENV_PASSPHRASE="old-passphrase" npx secure-env decrypt .env.enc .env

# Step 2: Re-encrypt using the new passphrase
ENV_PASSPHRASE="new-passphrase" npx secure-env encrypt .env .env.enc

After rotation, update ENV_PASSPHRASE in every environment that uses the file — local developer machines, deployment secrets, and server environment variables — before deploying the new .env.enc.

Delete or securely shred the intermediate plaintext .env file after re-encryption to avoid leaving secrets on disk.