dotenvx is an environment variable management tool that loads and encrypts .env files. Language- and framework-agnostic.
Installation
# curl(推奨)
curl -sfS https://dotenvx.sh | sh
# brew
brew install dotenvx/brew/dotenvx
# npm
npm install @dotenvx/dotenvx --save
Basic commands
# 環境変数を読み込んでコマンド実行
dotenvx run -- node index.js
# 特定の .env ファイルを指定
dotenvx run -f .env.production -- npm start
# 複数ファイル読み込み(後が優先)
dotenvx run -f .env -f .env.local -- npm start
# 環境変数を取得
dotenvx get DATABASE_URL
# 全環境変数を表示
dotenvx get
Encryption
# .env を暗号化(DOTENV_PUBLIC_KEY, DOTENV_PRIVATE_KEY 生成)
dotenvx encrypt
# 特定ファイルを暗号化
dotenvx encrypt -f .env.production
# 復号化
dotenvx decrypt
# 暗号化されたファイルを実行(DOTENV_PRIVATE_KEY が必要)
dotenvx run -- node index.js
How encryption works
dotenvx encryptRunning generates a public/private key pairDOTENV_PUBLIC_KEY: Stored in the .env file (for encryption)DOTENV_PRIVATE_KEY: Set in the local environment or CI (for decryption)- Per environment:
DOTENV_PRIVATE_KEY_PRODUCTIONautomatically determined by
Options
| Options | Description |
|---|---|
-f, --env-file |
Specify .env file |
--overload |
Overridden by subsequent files |
--quiet |
Suppress output |
--verbose |
Verbose display |
--debug |
Display debug information |
Managing multiple environments
.env # 共通設定
.env.local # ローカル上書き(gitignore)
.env.production # 本番環境
.env.development # 開発環境
# 本番環境で実行
dotenvx run -f .env.production -- npm start
# 開発 + ローカル上書き
dotenvx run -f .env.development -f .env.local -- npm run dev
Key Rotation
Procedure for when the private key is suspected of being leaked, or for periodic rotation.dotenvx rotate As of 2026/04, no dedicated command exists, so explicitly perform decrypt → encrypt with the new key.
Order is of utmost importance: CI secret を First update to the new key, then merge the new ciphertext. If reversed, prod will go down trying to decrypt the new ciphertext with the old key.
# 1. 作業ブランチ + 旧 key 退避
git switch -c chore/rotate-prod-dotenv-key
set +o history
OLD_PRIV="$DOTENV_PRIVATE_KEY_PRODUCTION"
# 2. 旧 key で復号(平文に戻す)
DOTENV_PRIVATE_KEY_PRODUCTION="$OLD_PRIV" dotenvx decrypt -f .env.production
# 3. 既存 PUBLIC_KEY を削除してから再 encrypt(新 key ペアが生成される)
sed -i.bak '/^DOTENV_PUBLIC_KEY_PRODUCTION=/d' .env.production
dotenvx encrypt -f .env.production
NEW_PRIV=$(dotenvx get DOTENV_PRIVATE_KEY_PRODUCTION -f .env.keys)
# 4. CI secret を新 key に更新(merge より先)
gh secret set DOTENV_PRIVATE_KEY_PRODUCTION --body "$NEW_PRIV" --env production
# 5. 新暗号文を commit + merge + deploy
git add .env.production && git commit -m "chore: rotate production dotenv key"
git push && gh pr create --fill && gh pr merge --squash --auto
# 6. クリーンアップ
unset OLD_PRIV; set -o history
rm .env.production.bak
Additional measures in case of leakage:
- Old ciphertext remaining in git history can still be decrypted with the past old key. Key rotation alone is insufficient
- The encrypted values themselves (DB password, API key, etc.) must also be reissued in parallel Required
- If complete removal from history is needed, use
git filter-repo, but be cautious as the impact of force push is significant
Avoiding downtime: Temporarily DOTENV_PRIVATE_KEY_PRODUCTION と DOTENV_PRIVATE_KEY_PRODUCTION_NEW can be kept in parallel, and a blue-green operation that deletes the old one after a successful deployment is also possible.
GitHub Actions
Install with curl. For a complete example, see assets/gh_action_example.yaml .
steps:
- uses: actions/checkout@v4
- name: Install dotenvx
run: curl -sfS https://dotenvx.sh | sh
- name: Run tests
env:
DOTENV_PRIVATE_KEY: ${{ secrets.DOTENV_PRIVATE_KEY }}
run: dotenvx run -- npm test