CLI Command Explainer

cmd-explain

承認する前に、あらゆるシェルコマンドの動作を把握できます。
AI コーディングエージェント向け MCP サーバー · Kiro、Cursor、VS Code、Windsurf、Claude Code に対応

英語 | 中国語

クイックスタート · 仕組み · 対応 IDE · ローカル AI

---

問題

AI コーディングエージェントは、あなたのマシン上でシェルコマンドを実行します。承認ダイアログは表示されますが、次のように推測するしかありません。

Agent wants to run:  curl -sL https://raw.githubusercontent.com/some-tool/install.sh | sudo bash

  [ Approve ]   [ Deny ]

安全なのでしょうか？-sL の意味は何でしょうか？なぜ sudo が必要なのでしょうか？多くの人は、何も考えずに承認するか（危険です）、検索して調べるか（時間がかかり、作業の流れが途切れます）のどちらかです。

解決策

cmd-explain は、シェルコマンドが実行される前にすべてのコマンドを捕捉し、リスク評価とともに平易な英語で説明を表示します。

🔴 Transfer data from or to a URL (silent, follow redirects),
   then GNU Bourne-Again SHell
   Risk: high · Source: built-in

Agent wants to run:  curl -sL https://raw.githubusercontent.com/some-tool/install.sh | sudo bash

  [ Approve ]   [ Deny ]

これで、そのコマンドがスクリプトをひそかにダウンロードし、root 権限で bash に渡して実行することがわかります。これは、1 行でルートキットを仕込める手段です。簡単に拒否できますし、少なくとも先に確認する価値があります。

その他の例

エージェントが実際に提案するコマンドです。何も考えずに承認してしまいそうなものを紹介します。

🔴 chmod -R 777 .
   Change file permissions (recursive)
   Risk: high · Source: built-in
   → Makes every file in your project world-writable

🟡 curl -sL https://install.example.com | bash
   Transfer data from or to a URL (silent, follow redirects),
   then GNU Bourne-Again SHell
   Risk: medium · Source: built-in
   → Downloads and executes a remote script. Classic supply chain risk.

🔴 git push origin main --force
   Upload local commits to a remote (force push, set upstream)
   Risk: high · Source: built-in
   → Overwrites remote history. Other people's commits may be lost.

🔴 rm -rf node_modules dist .next .cache && npm ci
   Remove files or directories (recursive, force without confirmation),
   then clean install from lockfile
   Risk: high · Source: built-in

🟡 npx prisma db push --accept-data-loss
   Run a command from a local or remote npm package without installing
   Risk: medium · Source: built-in
   → That --accept-data-loss flag means exactly what it says.

🔴 kubectl exec -it prod-db-0 -- psql -c "DROP TABLE users"
   Execute a command in a container
   Risk: high · Source: built-in
   → Running SQL directly on a production pod.

各説明には、次の情報が含まれます。

• 動作 — フラグやシェルのパターン（2>&1、|| true、>/dev/null）を含む、平易な英語での説明
• リスクレベル — 低（読み取り専用）、中（状態を変更）、高（破壊的）、不明
• 情報源 — built-in（241 コマンドの辞書）、system（man ページ）、ai-generated（LLM）

クイックスタート

npx cmd-explain setup

以上です。IDE を自動検出し、MCP サーバーをインストールして、コマンド実行前フックを作成します。IDE を再起動すれば、保護が有効になります。

要件： Node.js 18 以降。API キーも Ollama も不要で、編集が必要な設定ファイルもありません。

仕組み

cmd-explain は、explain_command というツールを 1 つ備えた MCP サーバー です。エージェントがシェルコマンドを実行しようとすると、コマンド実行前フックがこのツールを自動的に呼び出します。

説明は次の 3 つの層から、順番に確認して取得します。

層	情報源	速度	対応範囲	セットアップが必要？
1	組み込み辞書 — 240 以上のプログラムと 440 以上のコマンド説明（git、docker、npm、kubectl、terraform、aws、brew、cargo など）	<1ms	エージェントのコマンドの約 90%	いいえ
2	システムの man ページ — インストール済みの CLI ツールについて、whatis の出力を解析	約 50ms	インストール済みツールの大半	いいえ
3	ローカル AI — 1、2 層で見つからないものに対応する Ollama、OpenAI、Anthropic	約 1s	すべて	任意

1 層目と 2 層目は、依存関係なしで完全にオフラインで動作します。3 層目は任意で有効にできます。

シェルパターンの検出

cmd-explain は、エージェントがよく使うシェル構文を理解します。

パターン	注釈
2>&1	標準エラー出力を標準出力にリダイレクト
>/dev/null 2>&1	すべての出力を抑制
2>/dev/null	エラー出力を抑制
|| true	終了コードを無視
set -e	エラー時に終了
set -x	実行前にコマンドを表示
set -o pipefail	パイプ内のいずれかのコマンドでエラーが発生した場合に失敗
$(...)	コマンド置換

これらは説明に追加されるため、コマンド全体の動作を常に把握できます。

リスク分類

レベル	意味	例
🟢 低	読み取り専用で、副作用なし	ls、cat、grep、git status、curl GET
🟡 中	状態を変更するが、元に戻せる	git commit、npm install、mkdir、docker build
🔴 高	破壊的、または取り消し不可能	rm -rf、docker rm -f、terraform destroy、find -delete
⚪ 不明	認識されない	カスタム／独自仕様の CLI

対応 IDE

セットアップコマンドひとつですべて処理できます。各 IDE に適したフック形式が自動的に適用されます。

IDE	フックイベント	シェルの対応範囲
Kiro	preToolUse	✅ すべてのシェルコマンド
VS Code Copilot	PreToolUse	✅ すべてのシェルコマンド
Cursor	beforeShellExecution	✅ 専用のシェルフック
Windsurf	pre_run_command	✅ 専用のシェルフック
Claude Code	PreToolUse	✅ マッチャー経由

npx cmd-explain setup              # Auto-detect all IDEs
npx cmd-explain setup --ide kiro   # Target one IDE
npx cmd-explain setup --no-hooks   # MCP server only

オプション：ローカル AI

辞書や man ページにないコマンドについては、Ollama を利用したローカル AI の解説を有効にできます（一度だけ約 1GB のダウンロードが必要です）。

brew install ollama
brew services start ollama
ollama pull qwen2.5-coder:1.5b
npx cmd-explain setup --ollama qwen2.5-coder:1.5b

セットアップコマンドは各手順を検証します。Ollama がインストールされていない場合やモデルがプルされていない場合は、実行すべきコマンドを正確に知らせます。

クラウド API も利用できます。

npx cmd-explain setup --openai-key sk-...

対応プロバイダー：Ollama、OpenAI（OPENAI_API_KEY）、Anthropic（ANTHROPIC_API_KEY）。

手動インストール

IDE の MCP 設定に追加します。

{
  "mcpServers": {
    "cmd-explain": {
      "command": "npx",
      "args": ["-y", "cmd-explain"]
    }
  }
}

設定ファイルの場所：

• Kiro： .kiro/settings/mcp.json
• VS Code： .vscode/mcp.json
• Cursor： .cursor/mcp.json
• Windsurf： ~/.codeium/windsurf/mcp_config.json
• Claude Code： ~/.claude/settings.json

アンインストール

npx cmd-explain uninstall

検出されたすべての IDE から MCP 設定とフックファイルを削除します。クリーンに削除され、何も残りません。

プラットフォーム対応状況

	macOS	Linux	Windows
辞書（ティア 1）	✅	✅	✅
man ページ（ティア 2）	✅	✅	⚠️ --help のみ
ローカル AI（ティア 3）	✅	✅	✅
セットアップ CLI	✅	✅	✅

ライセンス

MIT