🔐 Secure, encrypted environment variables that live in your codebase

Features

• 🔒 Uses the battle-tested AES-256-GCM encryption algorithm
• 🔑 Keys can be exported anytime - no vendor lock-in
• 🚀 Secure command running with on-the-fly decryption
• ✍️ Easy and secure environment variable editing
• 🌍 Supports multiple and extensible environments
• 🔄 Offers a simplified key rotation process

How It Works

1. Environment variables are encrypted using a secure key
2. Encrypted files (.env.*.enc) are committed to your repository
3. Keys are stored securely and not committed to the repository
4. The local, git-ignored .env file can be used for development
5. When running commands, variables are decrypted on-the-fly

Installation

npm install -g @dotenc/cli

Usage

Initialize a New Environment

dotenc init [environment]

This will:

1. Create a new encrypted environment file (.env.[environment].enc)
2. Set up a local .env file for development
3. Create a dotenc.json configuration file

Edit an Environment

dotenc edit [environment]

Opens your system's default editor to modify the specified environment. To set a custom editor, use the dotenc config editor command. It will take precedence over your system's default editor.

Example:

dotenc config editor vim

Run Commands on an Environment

dotenc run --env <environment> <command> [...args]
# or
dotenc run -e <environment> <command> [...args]

Example:

dotenc run -e production node app.js

You can also specify multiple environments:

dotenc run -e base,production node app.js

In the example above, production will override any variables also present in base.

Key management

To import a key into your machine, use the key import command:

dotenc key import <environment> <key>

To export a key from your machine, use the key export command:

dotenc key export <environment>

To rotate a key, use the key rotate command:

dotenc key rotate <environment>

Use Cases

For convenience, you can setup your package.json file like this:

  // ...
  "scripts": {
    "dev": "dotenc run -e development tsx src/app.ts",
    "start": "dotenc run -e production node dist/app.js",
    "test": "dotenc run -e test vitest"
  }

Alternatively, the DOTENC_ENV variable can be used to set the environment, so the -e option can be omitted. For example:

  export DOTENC_ENV="production"
  dotenc run node app.js

Also, if a key is not present in your machine, you can use the DOTENC_KEY variable to decrypt an environment:

  DOTENC_KEY=<prod_key> dotenc run -e production node app.js

This can be useful for CI and automated platforms like Netlify and Vercel. Just export your keys and set the DOTENC_KEY variable in each environment.

The DOTENC_KEY variable also works with multiple environments:

  DOTENC_KEY=<base_key>,<prod_key> dotenc run -e base,production node app.js

License

MIT