dotenvx

dotenvx CLI

dotenvx は、dotenv の開発者が作成したセキュアな dotenv です。暗号化された環境変数、クロスプラットフォームの run による注入、複数環境への対応を提供します。

主な機能：

• dotenvx run — 任意のコマンド、任意の言語に環境変数を注入します
• dotenvx encrypt — 公開鍵暗号方式（secp256k1）で .env ファイルを暗号化します
• dotenvx set / get — 個々の環境変数を管理します
• dotenvx decrypt — .env ファイルを復号して平文に戻します
• -f フラグと DOTENV_PRIVATE_KEY_* の規約による複数環境への対応

インストール

# npm (local to project)
npm install @dotenvx/dotenvx --save

# global installs
curl -sfS https://dotenvx.sh | sh       # curl
brew install dotenvx/brew/dotenvx        # brew
winget install dotenvx                   # windows
docker run -it --rm -v $(pwd):/app dotenv/dotenvx help  # docker

Node.js では、ライブラリとしても使用できます：

require('@dotenvx/dotenvx').config()
// or: import '@dotenvx/dotenvx/config'

---

主なコマンド

dotenvx run

.env ファイルの環境変数を任意のプロセスに注入します。基本となるコマンドです。

dotenvx run -- <command>

フラグ：

フラグ	説明
-f <file>	環境ファイルを指定します。複数回指定できます。デフォルト：.env
--env KEY=value	環境変数をインラインで設定します
--overload	後のファイル／値で前の値を上書きします（デフォルトでは先に指定した値が優先されます）
--strict	エラー（ファイルが見つからない、復号に失敗するなど）があると終了コード 1 で終了します
--ignore=ERROR_CODE	特定のエラーを無視します（例：MISSING_ENV_FILE）
--convention=nextjs|flow	Next.js または dotenv-flow の規約に従ってファイルを読み込みます
-fk <path>	.env.keys ファイルのパスを指定します（モノレポで便利です）
--quiet	エラー以外のすべての出力を抑制します
--verbose	詳細なログを出力します
--debug	デバッグレベルのログを出力します
--log-level=<level>	ログレベルを設定します：error, warn, info, verbose, debug, silly

使用例：

# Basic usage
dotenvx run -- node index.js

# Specific env file
dotenvx run -f .env.production -- node index.js

# Multiple env files (first file's values win by default)
dotenvx run -f .env.local -f .env -- node index.js

# Override: last file wins
dotenvx run -f .env.local -f .env --overload -- node index.js

# Inline env var (overrides file values)
dotenvx run --env HELLO=String -f .env -- node index.js

# Any language works
dotenvx run -- python3 app.py
dotenvx run -- ruby index.rb
dotenvx run -- go run main.go
dotenvx run -- cargo run
dotenvx run -- php artisan serve
dotenvx run -- next dev

# Shell expansion (use subshell to prevent premature expansion)
dotenvx run --env="HELLO=World" -- sh -c 'echo Hello $HELLO'

# Strict mode for CI
dotenvx run -f .env.ci --strict -- node build.js

優先順位のルール：

• デフォルトでは、シェルにすでに設定されている環境変数が .env ファイルの値より優先されます
• 複数の -f ファイルを指定した場合、最初のファイルの値が優先されます（従来の dotenv の動作）
• --overload を指定すると、この動作が逆になり、後のファイルで前のファイルを上書きします
• --env フラグの値はファイルの値より優先されます

変数の展開と補間：

dotenvx は、.env ファイル内で ${VAR} の展開、デフォルト値、代替値、コマンド置換に対応しています：

# Variable expansion
USERNAME="admin"
DATABASE_URL="postgres://${USERNAME}@localhost/mydb"

# Default values (use fallback if unset/empty)
DB_HOST=${DB_HOST:-localhost}
DB_PORT=${DB_PORT:-5432}

# Alternate values (use alternate if variable IS set)
DEBUG_MODE=${NODE_ENV:+false}

# Command substitution
WHOAMI="$(whoami)"

複数行の値にも対応しています。二重引用符で囲みます：

CERT="-----BEGIN CERTIFICATE-----
MIIB...
-----END CERTIFICATE-----"

重要：dotenvx にない機能

以下の機能があると誤って案内しないでください。これらは存在しません：

• ❌ dotenvx keys — 代わりに dotenvx keypair を使用してください
• ❌ dotenvx status — このコマンドはありません
• ❌ dotenvx rotate — キーをローテーションするには、dotenvx set で値を更新するか、復号 → .env.keys を削除 → 再暗号化してください
• ❌ --env-name フラグ — 存在しません
• ❌ .env.vault ファイル — dotenvx は別個の vault ファイルではなく、ファイルをその場で暗号化します
• ❌ DOTENVX_PRIVATE_KEY — 正しい環境変数は DOTENV_PRIVATE_KEY です（途中に X は入りません）
• ❌ pip install dotenvx — Python パッケージはありません。dotenvx は任意の言語で使える CLI ツールです
• ❌ dotenvx.load_dotenv() — Python API はありません。CLI から dotenvx run -- python app.py を使用してください

---

dotenvx encrypt

.env ファイルをその場で暗号化します。DOTENV_PUBLIC_KEY（.env ファイルに追加）と DOTENV_PRIVATE_KEY（.env.keys に保存）を生成します。

dotenvx encrypt                     # encrypts .env
dotenvx encrypt -f .env.production  # encrypts specific file
dotenvx encrypt --stdout            # output to stdout instead of in-place

暗号化後：

• .env には暗号化された値と DOTENV_PUBLIC_KEY が含まれます
• .env.keys には DOTENV_PRIVATE_KEY が含まれます（秘密にして、絶対にコミットしないでください）
• 暗号化された .env はバージョン管理にコミットしても安全です

dotenvx decrypt

暗号化された .env ファイルを復号して平文に戻します。

dotenvx decrypt                     # decrypts .env
dotenvx decrypt -f .env.production  # decrypts specific file
dotenvx decrypt --stdout            # output to stdout

秘密鍵を使用できる状態にしておく必要があります（.env.keys ファイルまたは DOTENV_PRIVATE_KEY* 環境変数経由）。

dotenvx set

.env ファイル内の個々の環境変数を設定します。ファイルが存在しない場合は作成します。ファイルが暗号化されている場合は、自動的に再暗号化します。

dotenvx set KEY value                       # set in .env
dotenvx set KEY value -f .env.production    # set in specific file
dotenvx set KEY "multi word value"          # quoted values
dotenvx set KEY value -fk .env.keys -f apps/app1/.env  # monorepo

dotenvx get

単一の環境変数の値を取得します。

dotenvx get HELLO                          # from .env
dotenvx get HELLO -f .env.production       # from specific file
dotenvx get HELLO --env HELLO=Override     # from --env string
dotenvx get HELLO --overload               # with overload semantics
dotenvx get HELLO --strict                 # exit 1 if key missing
dotenvx get HELLO --convention=nextjs      # with convention
dotenvx get HELLO -fk .env.keys -f app/.env  # monorepo

すべてを JSON として取得：

dotenvx get                    # all vars from .env as JSON
dotenvx get -f .env.production # all vars from specific file
dotenvx get --all              # include DOTENV_PUBLIC_KEY
dotenvx get --format shell     # output as KEY=value lines

dotenvx keypair

暗号化された .env ファイルの公開鍵／秘密鍵のペアを出力します。

dotenvx keypair                              # all keypairs as JSON
dotenvx keypair DOTENV_PRIVATE_KEY           # just the private key
dotenvx keypair -f .env.production           # for specific file
dotenvx keypair DOTENV_PRIVATE_KEY_PRODUCTION -f .env.production

---

暗号化ワークフロー

初期設定

# 1. Create your .env
echo "DATABASE_URL=postgres://localhost/mydb" > .env
echo "API_KEY=sk-secret123" >> .env

# 2. Encrypt it
dotenvx encrypt
# ✔ encrypted (.env)
# Creates .env.keys with your private key

# 3. Commit .env (encrypted, safe), do NOT commit .env.keys
echo ".env.keys" >> .gitignore
git add .env .gitignore
git commit -m "add encrypted env"

複数環境の暗号化

環境ごとに専用の鍵ペアを使用します。命名規約は自動的に適用されます：

# Encrypt each environment
dotenvx encrypt -f .env.production
dotenvx encrypt -f .env.staging
dotenvx encrypt -f .env.ci

# Each creates a corresponding private key in .env.keys:
# DOTENV_PRIVATE_KEY_PRODUCTION="..."
# DOTENV_PRIVATE_KEY_STAGING="..."
# DOTENV_PRIVATE_KEY_CI="..."

実行時の復号

適切な DOTENV_PRIVATE_KEY_* 環境変数を設定すると、dotenvx run が自動的に復号します。

# The private key suffix matches the file suffix
DOTENV_PRIVATE_KEY="key"                  dotenvx run -- node app.js          # decrypts .env
DOTENV_PRIVATE_KEY_PRODUCTION="key"       dotenvx run -- node app.js          # decrypts .env.production
DOTENV_PRIVATE_KEY_CI="key"               dotenvx run -- node app.js          # decrypts .env.ci

# Combine multiple
DOTENV_PRIVATE_KEY="k1" DOTENV_PRIVATE_KEY_PRODUCTION="k2" dotenvx run -- node app.js

# Comma-separated keys for monorepos (same environment, different apps)
DOTENV_PRIVATE_KEY_CI="key1,key2" dotenvx run -f app1/.env.ci -f app2/.env.ci -- node app.js

CI/CD との統合

# GitHub Actions example
name: deploy
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsS https://dotenvx.sh/install.sh | sh
      - run: dotenvx run -- node build.js
        env:
          DOTENV_PRIVATE_KEY_PRODUCTION: ${{ secrets.DOTENV_PRIVATE_KEY_PRODUCTION }}

---

規約

--convention=nextjs

Next.js の優先順位に従ってファイルを読み込みます。

1. .env.$(NODE_ENV).local
2. .env.local
3. .env.$(NODE_ENV)
4. .env

dotenvx run --convention=nextjs -- next dev

--convention=flow

dotenv-flow の優先順位に従ってファイルを読み込みます。DOTENV_ENV または NODE_ENV を使用します。

DOTENV_ENV=development dotenvx run --convention=flow -- node app.js

---

モノレポのサポート

共有の .env.keys パスを指定するには、-fk を使用します。

# Set values for different apps
dotenvx set HELLO app1 -fk .env.keys -f apps/app1/.env
dotenvx set HELLO app2 -fk .env.keys -f apps/app2/.env

# Run with shared keys
dotenvx run -fk .env.keys -f apps/app1/.env -- node apps/app1/index.js

# Get values
dotenvx get HELLO -fk .env.keys -f apps/app1/.env

---

Docker

FROM node:latest
RUN curl -fsS https://dotenvx.sh/install.sh | sh
COPY . .
CMD ["dotenvx", "run", "--", "node", "index.js"]

または、直接実行します。

docker run -it --rm -v $(pwd):/app dotenv/dotenvx run -- node index.js

---

よく使うパターン

暗号化されたファイルに新しいシークレットを追加する：

dotenvx set NEW_SECRET "value" -f .env.production
# Automatically re-encrypts

値をローテーションする：

dotenvx set API_KEY "new-key-value" -f .env.production

コマンドを実行せずに復号済みの値を表示する：

dotenvx get -f .env.production           # needs private key available
dotenvx get API_KEY -f .env.production   # single value

既存のプレーンテキストの .env を暗号化する：

dotenvx encrypt -f .env.production
# Done. Commit the encrypted .env.production, store .env.keys privately.

スクリプトで dotenvx の出力を抑制する：

dotenvx run --quiet -- ./my-script.sh

環境変数の不足や不具合がある場合に CI を失敗させる：

dotenvx run -f .env.ci --strict -- npm test

---

.gitignore の推奨事項

# Never commit private keys
.env.keys

# Encrypted .env files ARE safe to commit
# !.env
# !.env.production
# !.env.staging

トラブルシューティング

• MISSING_ENV_FILE — 指定された .env ファイルが存在しません。ファイルを作成するか、--ignore=MISSING_ENV_FILE を使用してください。
• MISSING_KEY — 要求されたキーが .env ファイルにありません。
• 復号に失敗する — 正しい DOTENV_PRIVATE_KEY_* が設定されていることを確認してください。サフィックスはファイルのサフィックスと一致する必要があります（例：.env.production の場合は _PRODUCTION）。
• Deno + encrypt — deno run npm:@dotenvx/dotenvx encrypt は使用しないでください。Deno の暗号機能のサポートは不完全です。代わりに dotenvx をバイナリとしてインストールしてください。
• シェルが $VARS を早期に展開してしまう — サブシェルを使用してください：dotenvx run -- sh -c 'echo $MY_VAR'

---

拡張コマンド（dotenvx ext）

dotenvx のワークフローを管理するためのユーティリティコマンドです。

dotenvx ext genexample                  # generate .env.example from .env
dotenvx ext genexample -f .env.production  # from specific file
dotenvx ext gitignore                   # append .env.keys to .gitignore
dotenvx ext ls                          # list all .env files in project
dotenvx ext ls -f .env.production       # check specific file
dotenvx ext settings                    # view current dotenvx settings