kazuph/env-setup

Environment Setup Skill (dotenvx + direnv + worktree)

Git worktreeを使った並列開発で、環境変数を安全かつ効率的に管理する環境をセットアップします。

Core Principle

暗号化は常時維持: ディスク上は暗号化、メモリ上のみ復号。復号されたファイルが作られることはない。

ディスク上          メモリ上（実行時のみ）
┌─────────────┐     ┌─────────────┐
│ .env        │     │ DATABASE_URL=xxx │
│ (暗号化)    │ ──→ │ API_KEY=yyy      │
│ xxxxxxxxxx  │     │ (復号済み)       │
└─────────────┘     └─────────────────┘
     ↑                    ↑
  常にこの状態        プロセス実行中のみ

Tool Stack

| ツール | 役割 | インストール | |--------|------|-------------| | git-wt | Git worktree管理 | brew install k1LoW/tap/git-wt | | direnv | ディレクトリ単位で環境変数を自動読み込み | brew install direnv | | dotenvx | .envファイルの暗号化管理 | npm install -g @dotenvx/dotenvx |

Setup Instructions

以下の手順で環境をセットアップしてください。

Step 1: Check Prerequisites

まず必要なツールがインストールされているか確認:

# Check direnv
which direnv || echo "direnv not installed"

# Check dotenvx
which dotenvx || npm list -g @dotenvx/dotenvx || echo "dotenvx not installed"

# Check git-wt (optional but recommended)
git wt --version || echo "git-wt not installed (optional)"

インストールされていない場合は、ユーザーに案内してインストールを促す。

Step 2: Create/Encrypt .env File

既存の.envがあれば暗号化、なければサンプルを作成:

# If .env exists
dotenvx encrypt

# The .env.keys file will be generated with DOTENV_PRIVATE_KEY
# Extract the key for .envrc

Step 3: Create .envrc

以下の内容で.envrcを作成:

# .envrc
export DOTENV_PRIVATE_KEY="<key from .env.keys>"
eval "$(dotenvx decrypt --stdout --format shell)"

重要: .env.keysからDOTENV_PRIVATE_KEYの値を転記後、.env.keysは削除可能。

Step 4: Update .gitignore

以下を.gitignoreに追加（未追加の場合）:

.worktree
.artifacts
.envrc
.env.keys

Step 5: Activate direnv

direnv allow

Step 6: (Optional) Configure git-wt

Note: git-wtは**プロジェクトローカルな.worktree/**に配置する設計です。

.gitconfigで設定:

git config --global wt.basedir ".worktree"
git config --global wt.copyignored true
git config --global --add wt.hook "npm install || pnpm install || yarn install || true"

ディレクトリ構造:

myproject/
├── .worktree/
│   └── feature-auth/    # git wt feature-auth で作成
├── .envrc               # プロジェクトルートの環境変数
└── .env                 # 暗号化済み

direnvは親ディレクトリの.envrcを継承するため、プロジェクトルートに環境変数を設定しておけば、worktreeでも同じ環境変数が自動適用されます。

Multi-Environment Setup

複数環境を管理する場合:

Encrypt Each Environment

dotenvx encrypt -f .env.development
dotenvx encrypt -f .env.staging
dotenvx encrypt -f .env.production

Enhanced .envrc for Multiple Environments

# .envrc
export DOTENV_PRIVATE_KEY_DEVELOPMENT="xxx"
export DOTENV_PRIVATE_KEY_STAGING="yyy"
# DOTENV_PRIVATE_KEY_PRODUCTION は開発者には渡さない

# APP_ENVに応じて読み込む環境を決定
ENV_FILE=".env.${APP_ENV:-development}"

if [[ -f "$ENV_FILE" ]]; then
  eval "$(dotenvx decrypt -f "$ENV_FILE" --stdout --format shell)"
fi

CI/CD Integration

GitHub Actions example:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        env:
          DOTENV_PRIVATE_KEY: ${{ secrets.DOTENV_PRIVATE_KEY }}
        run: npx dotenvx run -- npm test

Command Reference

dotenvx

| コマンド | 説明 | |---------|------| | dotenvx encrypt | .envを暗号化 | | dotenvx encrypt -f .env.production | 特定ファイルを暗号化 | | dotenvx decrypt --stdout | 復号して標準出力 | | dotenvx decrypt --stdout --format shell | シェル形式で出力 | | dotenvx set KEY="value" | 変数を追加/更新（自動再暗号化） | | dotenvx get KEY | 変数の値を取得 | | dotenvx run -- <command> | 環境変数を注入してコマンド実行 | | dotenvx run --overload -- <command> | .envの値で既存環境変数を上書きして実行 | | dotenvx run --verbose -- <command> | スキップされた変数を表示して実行 | | dotenvx run --debug -- <command> | スキップされた変数の値まで表示して実行 |

⚠️ CRITICAL: --overload Flag and Silent Override Behavior

dotenvxのデフォルト動作は危険: 既存の環境変数が.envファイルの値より優先される。

シェル環境: FOO=bar (direnvなどで設定済み)
.envファイル: FOO=baz

# --overloadなし → FOO=bar のまま（.envの値は無視される）
dotenvx run -- echo $FOO  # → "bar"

# --overloadあり → FOO=baz に上書き
dotenvx run --overload -- echo $FOO  # → "baz"

最も危険なポイント: このスキップはデフォルトでサイレント。通知は--verbose/--debugでのみ表示される。

| フラグ | 出力 | |--------|------| | (なし) | 何も表示されない | | --verbose | FOO pre-exists (protip: use --overload to override) | | --debug | FOO pre-exists as bar (protip: use --overload to override) |

推奨: package.jsonのスクリプトでは常に--overloadを付ける:

{
  "scripts": {
    "dev": "dotenvx run -f .env.development --overload -- <start-cmd>",
    "test": "dotenvx run -f .env.development --overload -- <test-cmd>"
  }
}

ソースコード参照 (v1.51.4):

• 優先チェック: src/lib/helpers/parse.js — if (!this.overload && this.inProcessEnv(key))
• 通知: src/cli/actions/run.js — logger.verbose() / logger.debug() のみ（logger.warn() は使われていない）

git-wt

| コマンド | 説明 | |---------|------| | git wt <branch> | worktree作成 | | git wt | worktree一覧 | | git wt -d <branch> | worktree削除 |

direnv

| コマンド | 説明 | |---------|------| | direnv allow | .envrcを許可 | | direnv reload | 再読み込み |

Worktree Behavior

worktreeでも自動で動作する理由:

git-wt（プロジェクトローカル）の場合:

1. .worktree/ はプロジェクト内のサブディレクトリ
2. direnvは親ディレクトリの .envrc を自動継承
3. .env はgit管理なのでworktreeにも存在
4. 結果、worktreeでも自動で復号される

Modifying .env in Worktree

# git-wtで作成したworktreeに移動
cd .worktree/feature-x/

# 環境変数を追加/変更（自動で再暗号化される）
dotenvx set NEW_API_KEY="xxx"

# コミット
git add .env
git commit -m "feat: add NEW_API_KEY"

重要: dotenvx set は自動で再暗号化。.envを直接編集しない。

Benefits Summary

| 項目 | 効果 | |------|------| | セキュリティ | .envは常に暗号化、ディスク上に平文なし | | git管理 | 暗号化済み.envをコミット可能 | | チーム共有 | 鍵だけ共有すれば即動作 | | worktree | 親の.envrcを自動継承、設定不要 | | CI/CD | シークレット1つで全環境変数を管理 | | 権限分離 | 環境ごとに鍵を分けて権限制御可能 |

Execution Flow

このスキルを実行する際:

1. 現状確認: 既存の.env, .envrc, .gitignoreを確認
2. ツール確認: direnv, dotenvxのインストール状態を確認
3. セットアップ実行: Step 1-6を順番に実行
4. 検証: direnv allow後、環境変数が読み込まれるか確認

ユーザーに確認が必要な場合（既存ファイルの上書きなど）は必ず確認を取る。