> ## Documentation Index
> Fetch the complete documentation index at: https://encryptd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# encryptd Configuration: Path, Passphrase, and Environments

> Set up encryptd ConfigOptions: path, passphrase, and override. Securely provide ENV_PASSPHRASE across environments and manage multiple encrypted env files.

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:

```bash theme={null}
export ENV_PASSPHRASE="your-strong-passphrase"

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

<Tip>
  Add the `export` line to your shell profile (`.zshrc`, `.bashrc`, etc.) or use a tool like [direnv](https://direnv.net/) to load it automatically whenever you enter the project directory. Never commit the value to version control.
</Tip>

### 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:

```yaml .github/workflows/deploy.yml theme={null}
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
```

<Note>
  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.
</Note>

***

## 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:

```bash theme={null}
# 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:

```typescript src/index.ts theme={null}
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 });
```

<Tip>
  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`.
</Tip>

***

## `.gitignore` best practices

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

```gitignore .gitignore theme={null}
# 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.

<Warning>
  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.
</Warning>