dotenvx

Run a command with environment variables from a .env file

$ dotenvx run -- [command]

$ dotenvx run -f [path/to/file.env] -- [command]

$ dotenvx set [key] [value]

$ dotenvx set [key] [value] --plain

$ dotenvx get

$ dotenvx get [key]

$ dotenvx get --all

dotenvx [options] [command] [arguments...]

--help
    Displays help information for dotenvx or a specific command.

--version
    Shows the current version of dotenvx.

run <command> [args...]
    Executes a shell command with environment variables loaded from .env files.

encrypt [file]
    Encrypts a .env file into a .env.vault file using a DOTENV_KEY.

decrypt [file]
    Decrypts a .env.vault file back into a plain .env file.

genkey
    Generates a new secure DOTENV_KEY for encryption/decryption.

get <key>
    Retrieves the value of a specific environment variable.

set <key>=<value>
    Sets or updates an environment variable within the .env file.

ls
    Lists all environment variables loaded by dotenvx for the current environment.

cat
    Displays the raw content of a .env file, similar to the cat(1) command.

dotenvx is an advanced command-line tool for managing environment variables, extending the functionality of the widely-used dotenv concept. It addresses common challenges in configuration management by providing features like encryption, multi-environment support, and simplified sharing of sensitive variables.

The primary goal of dotenvx is to help developers and operations teams keep environment-specific configurations separate from codebase, enhancing security and portability. It allows for the encryption of sensitive data using a DOTENV_KEY, storing it in an encrypted .env.vault file, which can then be safely committed to version control.

It supports different environment files (e.g., .env.development, .env.production) and offers a robust CLI for tasks such as loading variables, encrypting/decrypting files, generating keys, and inspecting configurations. dotenvx streamlines the process of managing secrets and configuration in development, staging, and production workflows, ensuring that sensitive information remains protected while being easily accessible to authorized applications.

The security of dotenvx heavily relies on the secure management of your DOTENV_KEY. If this key is compromised, encrypted secrets can be exposed. It is crucial to store DOTENV_KEY securely and never commit it to source control. dotenvx is designed for managing application-specific environment variables and is not a full-fledged secret management system like HashiCorp Vault or cloud-native secret services, which offer more advanced features like auditing, access control, and secret rotation.

The DOTENV_KEY is a crucial encryption key used by dotenvx to encrypt and decrypt sensitive environment variables stored in .env.vault files. It's a base64-encoded AES-256 GCM key. This key must be securely managed (e.g., via environment variables, cloud secret managers) and never committed to your codebase. dotenvx provides the genkey command to generate new secure keys.

The .env.vault file is an encrypted representation of your .env file. Instead of storing plain text variables, dotenvx encrypts them and stores the encrypted blob along with metadata (like the environment it belongs to, e.g., DOTENV_VAULT_PRODUCTION) in this file. This allows you to safely commit .env.vault to your version control system without exposing secrets directly, as they can only be decrypted with the correct DOTENV_KEY.

dotenvx simplifies managing different configurations for various environments (e.g., development, test, staging, production). It prioritizes loading environment variables based on the active NODE_ENV or RAILS_ENV, looking for files like .env.<environment>.local, .env.<environment>, .env.local, and finally .env. This hierarchical loading ensures the correct variables are used for the specific deployment stage.

dotenvx emerged as a natural evolution of the popular dotenv ecosystem. While dotenv efficiently loads variables from a .env file into process.env, it lacked native support for encryption and multi-environment workflows, making secure secret management challenging, especially in production environments. dotenvx, developed by dotenv-org, was created to fill these gaps, introducing the concept of a DOTENV_KEY for encryption and the .env.vault file format. This development aimed to provide a more robust and secure solution for managing environment variables throughout the software development lifecycle, from local development to CI/CD pipelines and production deployments, without exposing sensitive information in plain text.

source(1), export(1), direnv(1), vault(1)