working-with-mise

mise を使う

概要

mise は複数言語に対応したツールバージョンマネージャーです。次の場合にこのスキルを使用します。

• mise を使ってプロジェクトにツールを追加する場合
• mise でツールが利用可能なはずなのに「コマンドが見つからない」問題をトラブルシューティングする場合
• 依存関係に mise が適しているか判断する場合

厳守事項

1. ツールの追加には mise use を使います。設定ファイルを手動で編集しないでください。
2. 既存の設定ファイルを先に確認します。既存のファイルがある場合、新しいファイルを作成しないでください。
3. 回避策ではなくシェルを修正します。ツールが PATH に見つからない場合、恒久的な回避策として mise exec を使うのではなく、有効化の問題を診断してください。

mise と代替手段の使い分け

プロジェクトごとにバージョンが重要な場合は mise を使う

プロジェクトによって異なるバージョンが必要になるツール：

• 言語ランタイム：node、python、ruby、go、rust
• インフラストラクチャツール：terraform、kubectl、helm
• バージョン間で互換性を損なう変更があるツール

# Good mise candidates - version sensitivity
mise use node@20      # Projects may need different Node versions
mise use [email protected]  # IaC often pins specific versions
mise use [email protected]     # Gemfiles often require specific Ruby

バージョンがほとんど問題にならない場合は Homebrew／システムを使う

バージョンを問わず、一貫したインターフェースを備えた安定した CLI：

• jq、yq - クエリ言語は安定しています
• gh、hub - GitHub CLI
• ripgrep、fd - 検索ツール
• tree、htop - システムユーティリティ

# Better as Homebrew - version doesn't matter
brew install jq gh ripgrep

判断チェックリスト

次の点を確認してください。

1. このプロジェクトの README／ドキュメントにバージョンが指定されていますか？ → mise
2. チームメンバーによって必要なバージョンが異なる可能性はありますか？ → mise
3. このツールにはバージョン間で互換性を損なう変更がありますか？ → mise
4. どこでも同じ方法で使う安定した CLI ですか？ → Homebrew

mise でツールを追加する

1. 既存の設定ファイルを先に確認する

ツールを追加する前に、プロジェクトで使われている設定形式を検出します。

# Check for existing mise config
ls -la mise.toml .mise.toml .mise.local.toml .tool-versions 2>/dev/null

設定ファイルの優先順位（mise は最初に見つかったファイルを使用します）：

• mise.toml または .mise.toml - 標準の mise 設定
• .mise.local.toml - ローカルのオーバーライド（通常は gitignore に登録されています）
• .tool-versions - レガシーな asdf 形式

設定ファイルが存在する場合は、その形式を使ってください。 新しいファイルを作成しないでください。

2. mise use を使ってツールを追加する

必ず CLI を使ってください。ツールが存在し、正常に動作することが検証されます。

# Add to project config (mise.toml or existing format)
mise use node@20

# Add to global config (~/.config/mise/config.toml)
mise use -g [email protected]

# Dry run to see what would happen
mise use --dry-run [email protected]

設定ファイルを手動で編集しないでください。mise use を使うと、次のことが保証されます。

• ツール／バージョンがレジストリに存在する
• ツールが正しくインストールされる
• 設定の構文が有効である

3. ツールが利用可能であることを確認する

# Check mise sees the tool
mise ls

# Check the tool is on PATH
which node
node --version

# Compare with mise's view
mise which node

「コマンドが見つからない」問題のトラブルシューティング

ツールが利用可能なはずなのに見つからない場合：

診断の手順

# 1. Check mise installation health
mise doctor

# 2. Check what tools mise knows about
mise ls                    # All installed tools
mise ls --current          # Tools for current directory

# 3. Compare which vs mise which
which node                 # What shell finds
mise which node            # What mise thinks it should be

# 4. Check if tool would work via mise exec
mise exec -- node --version  # If this works, it's an activation issue

よくある原因と修正方法

シェルの有効化が設定されていない

症状：mise exec -- node は動作するが、node は動作しない

診断：

mise doctor  # Look for activation warnings

修正方法 - シェルの rc ファイルに追加します。

# For zsh (~/.zshrc)
eval "$(mise activate zsh)"

# For bash (~/.bashrc)
eval "$(mise activate bash)"

# For fish (~/.config/fish/config.fish)
mise activate fish | source

その後、シェルを再起動するか、rc ファイルを source します。

設定ファイルが信頼されていない

症状：mise に信頼に関する警告が表示され、ツールが有効化されない

修正方法：

mise trust

現在のディレクトリにツールがインストールされていない

症状：mise ls にはツールが表示されるが、mise ls --current には表示されない

診断：

# Check what config file applies
mise config

# Check if there's a local config overriding global
cat mise.toml .mise.toml .tool-versions 2>/dev/null

修正方法：プロジェクトの設定にツールを追加します。

mise use node@20  # Adds to project config

シムと PATH による有効化の混同

症状：ターミナルではツールが動作するが、IDE／スクリプトでは動作しない

詳しい説明は references/dev-tools/shims-html.md を参照してください。

非対話型の環境での簡易的な修正方法：

# In ~/.zprofile or ~/.bash_profile (non-interactive)
eval "$(mise activate zsh --shims)"

# In ~/.zshrc or ~/.bashrc (interactive)
eval "$(mise activate zsh)"

mise exec を（正当な用途で）使う場合

mise exec が適切な用途：

• 特定のバージョンを指定した単発コマンド：mise exec node@18 -- npm test
• 有効化を利用できない CI/CD スクリプト
• 一時的に別のバージョンをテストする場合

mise exec は次の問題の修正には使えません。

• ターミナルの PATH にツールがない（有効化の問題を修正してください）
• 恒久的な解決策として「mise exec なら動作する」状態にすること

GitHub の 401／トークンエラーのトラブルシューティング

症状：GitHub からツールを取得する際、mise install または mise use が 401 Unauthorized で失敗する

優先順位の高いソースにある期限切れのトークンは、下位にあるすべてのソースを黙ってシャドーイングします。不正なトークンはトークンがない場合よりも厄介です。GitHub は無効な認証情報には 401 を返しますが、匿名リクエストは（レート制限の範囲内で）成功するためです。

1. mise が選択したソースを確認する

mise token github    # masked output - safe to paste into logs
# github.com: gho_…tSoC (source: gh CLI (hosts.yml))

2. トークンの優先順位 — 最初に一致したものを使用

1. MISE_GITHUB_TOKEN
2. GITHUB_API_TOKEN
3. GITHUB_TOKEN
4. github.credential_command
5. ネイティブの GitHub OAuth
6. ~/.config/mise/github_tokens.toml
7. gh CLI の hosts.yml — デフォルトで有効になっており、よくある原因です
8. git credential fill — オプトイン

このリストには、注意すべき点が 2 つあります。

• GH_TOKEN は mise のトークンソースではありません。 gh 独自の変数なので、エクスポートしても何も変わりません。GITHUB_TOKEN または MISE_GITHUB_TOKEN を使用してください。
• 空の場合は未設定として扱われます。 GITHUB_TOKEN= mise install はそのまま hosts.yml にフォールバックします。このファミリーの環境変数を設定しても、mise は匿名では動作しません。

3. gh CLI の落とし穴

mise は ~/.config/gh/hosts.yml を直接読み込みます。gh をシェルから呼び出すことはありません。 そのため、gh 独自の有効期限処理は実行されず、古い oauth_token が 401 を返し続けます。

解決方法 — 再認証します。

gh auth login -h github.com

または gh との連携を無効にします — GH_CONFIG_DIR を空のディレクトリに設定するよりもすっきりした方法です。

MISE_GITHUB_GH_CLI_TOKENS=0 mise install    # mise token github -> (none)

~/.config/mise/config.toml で恒久的に設定します。

[settings.github]
gh_cli_tokens = false

GitHub Enterprise、credential_command、キーチェーンに保存されたトークンについては、references/dev-tools/github-tokens-html.md を参照してください。

検証コマンド

設定を変更した後、すべてが動作することを確認します。

# Full health check
mise doctor

# Verify specific tool
mise which node && node --version

# Verify PATH includes mise tools
echo $PATH | tr ':' '\n' | grep mise

利用可能なリファレンス

• references/cli/use-html.md - mise use の全ドキュメント
• references/cli/doctor-html.md - 診断コマンド
• references/cli/activate-html.md - シェルのアクティベーション
• references/cli/which-html.md - パスの解決
• references/dev-tools/shims-html.md - シムと PATH アクティベーションの比較
• references/dev-tools/github-tokens-html.md - GitHub トークンのソースと優先順位
• references/guides/getting-started.md - セットアップガイド

違反につながる危険な兆候

• 「これを mise.toml に手動で追加しよう」→ 代わりに mise use を使用してください
• 「回避策として mise exec を使おう」→ アクティベーションが機能しない理由を診断してください
• 「.mise.toml を作成しよう」→ まず設定ファイルがすでに存在するか確認してください
• jq/gh/ripgrep を mise に追加する → 実際にバージョンが重要か検討してください
• mise がアクティベート済みだと思い込む → mise doctor を実行して確認してください
• mise の 401 を解決するために GH_TOKEN をエクスポートする → mise はこの変数を読み取りません。まず mise token github を実行してください