ほりひログ

所属組織の製品 (Azure とか) に関連する内容が多めだけど、個人の見解であって、所属組織を代表する公式情報ではないです。

.envを自動解決してCLIを実行するコマンドプロキシ runx

くだらぬもの runx shellscript go

はじめに

ディレクトリごとに使う環境変数を切り替えたい場面は、クラウド運用やアプリ開発で頻出する。特に Azure CLI のように、同じコマンドで複数プロファイルを使い分けるケースでは、毎回 export したり、実行オプションを長く書いたりする手間が積み重なりやすい。

このエントリでは、runx が解決する課題、開発の背景、動作の仕組みを短く整理し、Azure CLI の具体例で使い方をまとめる。

結論

runx は、いつものコマンド名のまま、実行時に env ファイルを解決して環境変数を注入できるコマンドプロキシマネージャ。

  • runx add を一度実行すれば、以後は通常どおり az や terraform を実行可能
  • env ファイルは実行ディレクトリから親へ、最後にホームまで探索
  • 複数 --envfile は左から順にマージし、後勝ちで上書き

常時自動読み込みより、コマンド実行時だけ適用したい運用に向いた選択肢。

runxとは

runx は、環境変数ファイルを読み込んでからコマンドを実行するためのクロスプラットフォームツール。単一バイナリで動作し、Linux/macOS/Windows に対応する。

主な特徴は次のとおり。

  • コマンドプロキシを作成し、通常のコマンド呼び出しで env を反映
  • 実行時のディレクトリに応じた env ファイル探索
  • 複数 env ファイルのレイヤー合成（後勝ち）
  • runx exec による一回限り実行
  • runx env で、実際に注入される内容を事前確認

インストール

まずは GitHub Releases から取得するのが簡単。

github.com

Linux では .deb パッケージ、または tar.gz の単体バイナリを利用できる。

curl -LO https://github.com/horihiro/runx/releases/download/v<version>/runx_<version>_<arch>.deb
sudo apt install ./runx_<version>_<arch>.deb
runx --version

tar.gz を使う場合は次のとおり。

curl -LO https://github.com/horihiro/runx/releases/download/v<version>/runx-<os>-<arch>-v<version>.tar.gz
tar xzf runx-<os>-<arch>-v<version>.tar.gz
sudo install -m 0755 runx /usr/local/bin/runx
runx --version

Windows では winget で導入できる。

winget install --id horihiro.runx
runx --version

ソースから試したい場合は、Go が入った環境で go build でもビルド可能。

なぜ作ったか

背景はシンプルで、プロジェクトごとに設定を分けつつ、操作感は変えたくないという要求にある。

例えば Azure CLI では、AZURE_CONFIG_DIR を切り替えることで認証情報や設定を分離できる。一方で、都度エクスポートしたり、ラッパースクリプトを手で管理したりすると、運用が増えるほど管理コストは上がっていく。

runx の設計方針は次の三点。

  • 普段のコマンド体験を壊さない
  • 実行時コンテキスト（カレントディレクトリ）を素直に利用
  • OS 差分をツール側で吸収

仕組みの概要

内部では、runx add で元コマンドを呼ぶ薄いプロキシを作成する。

  • Linux/macOS: シェル設定に関数を追加
  • Windows: .cmd プロキシを配置（User/Machine PATH を判定）

プロキシから runx exec が呼ばれ、指定した env ファイル候補を解決し、環境変数を注入してから実コマンドを実行する流れ。

env ファイル解決ルールは次の順序。

  1. 絶対パス指定ならそのパスのみ確認
  2. ファイル名指定なら、カレントディレクトリから親へ順に探索
  3. 見つからなければホームディレクトリを最後に確認

複数ファイルを指定した場合は左から順に読み込み、同一キーは後ろのファイルで上書きされる。

使い方（Azure CLIを例に）

AZURE_CONFIG_DIR をディレクトリごとに切り替える最小構成の例を示す。

  1. ディレクトリと env ファイルを用意
mkdir -p ~/work/az_profile1 ~/work/az_profile2

cat > ~/work/az_profile1/.azclienv <<'EOF'
AZURE_CONFIG_DIR=~/.azure_profile1
EOF

cat > ~/work/az_profile2/.azclienv <<'EOF'
AZURE_CONFIG_DIR=~/.azure_profile2
EOF
  1. az をプロキシ登録
runx add az --envfile=.azclienv
  1. 通常どおり az を実行
cd ~/work/az_profile1
az account show

cd ~/work/az_profile2
az account show

初回のみ、各プロファイルで az login が必要になる。現在位置で注入される内容を確認したい場合は runx env az が有効。

他ツールとの比較

この領域には実績あるツールが既にあり、runx は置き換えよりも使い分けの位置づけになる。

  • direnv
    • ディレクトリ入退場に応じた自動ロード/アンロード
    • 常時フック型の自動化に強み
    • Windows 非対応
  • dotenv-cli / dotenvx 系
    • 一回実行の明示的な env 注入に強み
    • コマンドごとの明示実行がわかりやすい
  • runx
    • add/list/remove で永続プロキシを管理
    • コマンド名はそのまま、実行時だけ env を適用
    • Windows の PATH 優先順位まで含めて吸収

どれが優れているかという話より、 自動フック中心か、明示実行中心か、普段のコマンド体験を維持したいかで選ぶのが自然。

制限・注意点

運用前に把握しておくとハマりにくいポイントを列挙する。

  • Linux/macOS では runx add 後にシェル設定の再読み込みが必要
  • Windows では元コマンドが Machine PATH にあると runx add に管理者権限が必要
  • env ファイルが見つからない、または構文不正のときは期待どおりに実行できない
  • 同じコマンドに対して他のラッパー機構を併用すると競合する可能性

調査時は RUNX_DEBUG=2 を使うと探索パスを追えるため、原因切り分けが速い。

まとめ

runx は、環境変数の切り替えを日常のコマンド操作に自然に埋め込むためのツール。

複数クラウド環境や複数プロファイルを行き来するチームでは、 毎回意識して切り替える負担を下げ、操作ミスの抑制にもつながる。

まずは runx exec の一回実行で試し、手応えがあれば runx add で常用コマンドをプロキシ化する流れがおすすめ。