encryptd Configuration: Path, Passphrase, and Environments

encryptd is designed to work with sensible defaults and minimal configuration. The config() function accepts an optional options object that lets you customise the encrypted file path, provide the passphrase inline, and control whether existing process.env values are overwritten. This page covers every available option, how to supply your passphrase securely across different environments, and patterns for managing multiple encrypted files per deployment stage.

`config()` options reference

All options are optional. When you omit an option, config() applies the default listed below.

Option	Type	Default	Description
`path`	`string`	`".env.enc"`	Path to the encrypted env file, resolved relative to `process.cwd()`. Accepts both relative and absolute paths.
`passphrase`	`string`	`process.env.ENV_PASSPHRASE`	Passphrase used for PBKDF2 key derivation and AES-256-GCM decryption. Falls back to `ENV_PASSPHRASE` when omitted. Throws if neither source provides a value.
`override`	`boolean`	`false`	When `false`, keys already present in `process.env` are preserved. Set to `true` to overwrite them with values from the encrypted file.

Setting `ENV_PASSPHRASE`

encryptd reads the passphrase from the ENV_PASSPHRASE environment variable when you do not supply options.passphrase explicitly. This approach keeps the passphrase out of your source code entirely.

In your local shell

Export ENV_PASSPHRASE in your current terminal session before running the CLI or starting your application:

export ENV_PASSPHRASE="your-strong-passphrase"

# The CLI and config() both pick it up automatically
npx secure-env encrypt
node dist/index.js

Add the export line to your shell profile (.zshrc, .bashrc, etc.) or use a tool like direnv to load it automatically whenever you enter the project directory. Never commit the value to version control.

In GitHub Actions

Store the passphrase as an encrypted repository secret and inject it into your workflow via the env block. encryptd will read it from ENV_PASSPHRASE automatically:

.github/workflows/deploy.yml

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      ENV_PASSPHRASE: ${{ secrets.ENV_PASSPHRASE }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: node dist/index.js

Add ENV_PASSPHRASE under Settings → Secrets and variables → Actions in your GitHub repository. The value is masked in workflow logs and never exposed in plain text.

Using multiple env files per environment

When you manage distinct configurations for staging, production, or other deployment targets, encrypt each .env file separately and commit all the resulting .enc files:

# Encrypt each environment's variables into its own file
ENV_PASSPHRASE="s3cr3t" npx secure-env encrypt .env.staging .env.staging.enc
ENV_PASSPHRASE="s3cr3t" npx secure-env encrypt .env.prod    .env.prod.enc

Select the correct file at runtime with `NODE_ENV`

Use a NODE_ENV-based lookup in your application’s entry point to load the right file automatically:

src/index.ts

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

const encryptedFilePaths: Record<string, string> = {
  staging:    '.env.staging.enc',
  production: '.env.prod.enc',
};

const env = process.env.NODE_ENV ?? 'production';
const filePath = encryptedFilePaths[env] ?? '.env.enc';

config({ path: filePath });

You can use any environment variable not just NODE_ENV to drive the file selection. A dedicated APP_ENV variable is often clearer than overloading NODE_ENV.

`.gitignore` best practices

Commit your encrypted .env.enc files and exclude all plaintext .env files. Add the following block to your .gitignore:

.gitignore

# Exclude all plaintext env files
.env
.env.*

# Re-include encrypted env files (safe to commit)
!.env.enc
!.env.*.enc

This pattern ensures that:

.env, .env.staging, .env.prod, and any other plaintext variants are never staged accidentally.
.env.enc, .env.staging.enc, .env.prod.enc, and similar encrypted files remain tracked in version control so your team and CI pipeline can decrypt them with the shared passphrase.

Run git status after updating .gitignore to confirm that no plaintext .env files are currently tracked. If a file was committed before the rule was added, use git rm --cached .env to stop tracking it without deleting it from disk, then commit the removal.

​config() options reference

​Setting ENV_PASSPHRASE

​In your local shell

​In GitHub Actions

​Using multiple env files per environment

​Select the correct file at runtime with NODE_ENV

​.gitignore best practices

`config()` options reference

Setting `ENV_PASSPHRASE`

In your local shell

In GitHub Actions

Using multiple env files per environment

Select the correct file at runtime with `NODE_ENV`

`.gitignore` best practices