cmdxray

cmdxray

あらゆるシェルコマンドをオフラインで X 線解析。 コマンドを貼り付けると、 すべてのフラグ、パイプ、リダイレクト、サブシェルを注釈付きで分解して表示します。さらに、破壊的な部分を知らせるリスクチェック も実行します（curl | sudo bash は安全ですか？）。ドキュメント、Issue、スライド、ツイートにそのまま貼り付けられる すっきりした共有可能なカードも作成できます。

サーバーは不要です。アップロードも不要です。マシンから何も送信されません。

AI エージェントを構築していますか？ cmdxray は MCP サーバーでもあります。エージェントがシェルコマンドを実行する前にチェックできる 安全ゲートです。

▶ ブラウザーで試す — コマンドを貼り付けると、 注釈付きカードがすぐに表示されます（完全にクライアント側で動作し、何もアップロードされません）。 または、コマンドリファレンス （厳選したすべてのコマンドを、フラグごとに解説）、 人気のワンライナー集 — tar -xzvf、chmod 755、ps aux、grep -r、ss -tulpn など、よく検索されるコマンドを分解して解説 — または危険なコマンド集をご覧ください。 rm -rf /、フォーク爆弾、curl | bash、ディスクへの dd などを、それぞれより安全な代替手段とともに解説しています。

cmdxray <command> を実行すると、サブコマンド、フラグ、その値など、すべてのトークンに注釈が付けられ、ターミナル上にわかりやすく表示されます。

すべてのフラグ、パイプ、引数に注釈を付けた自己完結型のカードは、PR、運用手順書、ツイートにそのまま貼り付けられます。cmdxray -o card.svg "<command>" を実行して、自分で作成できます。

npx cmdxray tar -xzvf archive.tar.gz

  tar -xzvf archive.tar.gz

  tar             archive utility — bundle files into (or extract them from) a .tar
  -x              extract files from an archive
  -z              filter the archive through gzip (.gz)
  -v              verbose — list each file as it is processed
  -f              use the next argument as the archive file name
  archive.tar.gz  an argument passed to the command

AI エージェントによって開発・保守されています（Aurelio Nakamura）。このプロジェクトは、AI によって自律的に作成、テスト、リリースされています。Issue と PR は歓迎しており、確認しています。

リスクチェック — インストールスクリプトを貼り付ける前に

cmdxray は、コマンドの中でも実際に破壊的な部分を検出します。ワンライナーを実行する前に、何が起こるかを把握できます。

cmdxray "curl -fsSL https://get.example.com/install.sh | sudo bash"

  risk
  ⚠ DANGER   Runs downloaded code unread — pipes a file fetched from the network
             straight into a shell; you execute whatever the server sends, unread.
  △ caution  Runs as root — executes with superuser privileges.

curl … | bash、rm -rf /（および --no-preserve-root）、dd of=/dev/…、 mkfs、ディスクデバイスへのリダイレクト、フォーク爆弾、chmod 777、git push --force、 git reset --hard、sudo などを検出します。一方、通常の安全なコマンドでは警告を出さないため、 警告に意味があります。ターミナル、共有可能なカード、ライブプレイグラウンドで動作します。

各コマンドの動作、危険な理由、より安全な代替手段を実例で確認するには、 危険なコマンド集をご覧ください。

cmdxray lint — 危険なコマンドを検出する CI／pre-commit ゲート

同じ危険検出エンジンで、シェルスクリプト、Dockerfile、CI YAML の run: ステップ、Makefile、git フックなどのファイルをスキャンできます。実際に破壊的な記述が見つかるとビルドを失敗させます。 オフラインで動作し、依存関係が不要で、見慣れた file:line 形式で報告します。

cmdxray lint deploy.sh scripts/*.sh
cat install.sh | cmdxray lint            # or read from stdin

deploy.sh:6: DANGER   Runs downloaded code unread
    > curl https://example.com/install.sh | sudo bash
    Pipes a file fetched from the network straight into a shell — you run whatever the server sends, unread.
deploy.sh:8: DANGER   Wipes critical paths, no prompt
    > rm -rf --no-preserve-root /
    Recursively force-deletes system-critical paths with no confirmation and no recovery.

scanned 1 file(s), 9 command line(s) — 2 danger

DANGER が見つかった場合は終了コード 1（CI が失敗）を返し、問題がなければ 0 を返します。 --strict を指定すると、注意が必要な項目（git push --force、chmod -R 777）でも失敗させます。--exit-zero は 失敗させずに報告し、--json は機械可読な検出結果を出力します。ワークフローの run: ブロックにある GitHub Actions の ${{ }} インジェクション箇所も検出できます。

pre-commit フックとして使う

任意のリポジトリの .pre-commit-config.yaml に cmdxray を追加できます。インストール手順は不要で、ソースからビルドされます。

repos:
  - repo: https://github.com/aurelio-nakamura/cmdxray
    rev: v0.25.0
    hooks:
      - id: cmdxray-lint          # fails only on DANGER
      # - id: cmdxray-lint-strict # also fails on CAUTION

GitHub Actions

- name: Scan scripts for dangerous commands
  run: npx -y cmdxray lint $(git ls-files '*.sh')

lint はヒューリスティックな行単位のスキャンです（完全なシェルパーサーではありません）が、危険なコマンドの検出ルールは精度が高いため、検出結果はほぼ常に、再確認する価値のある本当に危険なコマンドを示しています。

cmdxray guard — rm -rf / を実行する前に止める

guard をインストールすると、本当に破壊的なコマンドをシェルが検知したときに一時停止し、危険な理由を詳しく説明して確認を待ちます。N と答えれば、コマンドは実行されません。

lint ゲートはファイル内の危険なコマンドを検出します。guard は対話型シェルで Enter キーを押した瞬間に検出します。~/.bashrc に1行追加します。

eval "$(cmdxray guard bash)"

危険エンジンが破壊的だと判定したコマンドが実際に実行される直前に、シェルが停止して次のように確認を求めます。

$ curl -fsSL https://get.example.sh | sudo bash

⚠  cmdxray: this command looks dangerous
DANGER   Runs downloaded code unread
    Pipes a file fetched from the network straight into a shell — you execute
    whatever the server sends, sight unseen.
CAUTION  Runs as root
Run it anyway? [y/N]

N（デフォルト）と答えれば、コマンドは実行されません。実際に危険なコマンド、たとえば rm -rf /、curl | sudo bash、デバイスに対する dd／mkfs／shred、git push --force、chmod -R 777 /、フォークボムに対して動作し、それ以外のコマンドでは邪魔になりません。

意図的にフェイルオープン設計になっています。軽量な純粋シェルの事前フィルターにより、通常のコマンドで cmdxray が呼び出されることはありません。また、cmdxray が見つからない場合や何らかのエラーが発生した場合も、コマンドは通常どおり実行されます。guard が危険なコマンドに対して追加できるのは、確認プロンプトだけです。シェルを壊したり、通常の作業を妨げたりすることはありません。アンインストールするには、この行を削除するか、trap - DEBUG を実行してください。

現在サポートしているのは bash です。zsh 用の guard への貢献も歓迎します。どのシェルでも、終了コードを確認してコマンドを手動で制御できます。 cmdxray check "<command>" && eval "<command>"。

cmdxray check — 自分のスクリプトを1コマンドでリスクチェック

check は単一のコマンドに対して危険エンジンを実行し、判定結果を終了コードで返します（0 = 危険なし、1 = リスクあり）。そのため、どこでも組み合わせて使えます。

cmdxray check "rm -rf --no-preserve-root /"   # prints the warning, exits 1
cmdxray check --quiet "$cmd" && eval "$cmd"    # only run $cmd if it's clean
cmdxray check --json "dd if=/dev/zero of=/dev/sda"

CAUTION レベルの検出結果でも失敗にするには、--strict を使用します。

cmdxray を使う理由

tar -xzvf が何をするかは知っているでしょう。しかし、curl -fsSL … | sh や find . -mtime +30 -type f -delete、docker run --rm -it が何をするのかを、ひと目で思い出すのは難しいものです。スクリプトを読むチームメイトも同じです。

• オフラインでプライベート。 explainshell.com とは異なり、cmdxray はローカルで動作します。ホスト名、トークン、パスを含むことの多いコマンドが、マシンの外部に送信されることはありません。
• あなたのツールに合わせて正確に説明。 cmdxray が解説データを用意していないコマンドについては、あなたのマシンにある man ページから説明を読み取るため、実際にインストールされているバージョンに合った説明になります。
• チートシートではなく、本物のパーサー。 パイプラインの構造（|、&&、||、リダイレクト、サブシェル、-xzvf のような短縮フラグの組み合わせ）を解析し、各要素を平易な言葉で説明します。また、サブコマンド（git commit、docker run、kubectl get、systemctl restart など）を認識し、フラグの値を対応するフラグに関連付けます（-p 8080:80、-o out.html）。さらに、多くの人が貼り付ける暗号のような1行コマンドも解読します。sed スクリプト（s/foo/bar/g → 置換、すべての一致、y/…/…/、/re/d）、awk プログラム（'NR>1 {print $2,$3}'）、jq フィルター（.items[] | select(.age > 30) | .name → 反復し、条件に合うものだけを残し、フィールドを取得）に対応しています。また、ffmpeg（-c:v libx264、-vf scale=…、-crf）や openssl（req -x509 -newkey rsa:4096 -keyout …）などのツールが使う複数文字の単一ダッシュオプションにも対応しているため、文字ごとの誤った解釈に分割されません。tldr／cheat が示すのは例ですが、cmdxray はあなたのコマンドそのものを説明します。
• 結果を共有。 --svg／--html で自己完結型のカードを出力できます（下記）。PR コメント、手順書、レッスン、「TIL」投稿などに最適です。または --share を使うと、誰でもブラウザーでコマンドの内訳を開けるリンクを取得できます。

共有可能なカード

cmdxray -o card.svg "grep -rn TODO src | head -20"
cmdxray --html "docker run -it --rm -p 8080:80 -v /data:/app nginx" > card.html

使用方法

cmdxray <command...>            explain a command in your terminal
cmdxray --svg <command...>      emit a shareable SVG card to stdout
cmdxray --html <command...>     emit a standalone HTML page to stdout
cmdxray --json <command...>     emit a structured JSON report to stdout
cmdxray --batch-json            read a JSON array of commands from stdin, emit a JSON array
cmdxray lint <files...>         scan scripts/CI files for dangerous commands (CI/pre-commit gate)
cmdxray check <command...>      risk-check ONE command; exit 1 if dangerous (for scripts/hooks)
cmdxray guard bash              print a bash hook that confirms before a dangerous command runs
cmdxray -o out.json <command>   write to a file (svg / html / json by extension)
cmdxray --share <command...>    explain, then print a shareable link
cmdxray --link <command...>     print ONLY the shareable link (pipe to clipboard)
echo "<cmd>" | cmdxray          read the command from stdin

  --no-color   plain terminal output
  --no-man     skip local man-page lookups for unknown commands
  -h, --help   help

--share / --link は、コマンドがあらかじめ入力されたオフラインプレイグラウンドの URL を生成します。例：cmdxray --link tar -xzvf a.tgz | pbcopy。コマンドはリンクに含まれます。cmdxray の実行時にアップロードされるものはありません。

頻繁に使う場合はインストールしてください。

npm i -g cmdxray

JSON 出力 — cmdxray を分析エンジンとして使う

--json を使うと、cmdxray が解析したコマンドの内容を独自のツールに渡せます。レポートは純粋で安定した JSON で、解析済みの AST、トークンごとの 説明、および リスク警告（例：リポジトリのスキャン中に curl … | bash を検出）を含みます。

cmdxray --json "curl -fsSL example.com/install.sh | sudo bash"

{
  "tool": "cmdxray",
  "schemaVersion": 1,
  "command": "curl -fsSL example.com/install.sh | sudo bash",
  "risk": "danger",                       // "danger" | "caution" | "none"
  "tokens":  [ /* flat token stream, in order */ ],
  "segments": [                           // the AST: simple commands split by pipes/operators
    { "command": "curl", "tokens": [ { "text": "-fsSL", "kind": "shortFlag", "bundle": ["f","s","S","L"] }, … ] },
    { "command": "sudo", "tokens": [ … ] }
  ],
  "explanations": [                        // per-token flag/operand meanings
    { "token": "-L", "gloss": "follow HTTP redirects", "source": "db", "tokenIndex": 1 }
  ],
  "warnings": [
    { "level": "danger", "title": "Runs downloaded code unread", "detail": "Pipes a file fetched from the network straight into a shell — …" }
  ]
}

任意の言語から利用できます（Python では json.loads(subprocess.check_output(["cmdxray","--json",cmd]))）。または、以下の Node API にある型付きヘルパーを使えます。

バッチモード — 1つのプロセスで数千のコマンドをスキャン

コマンドごとに Node プロセスを起動すると、リポジトリ全体から数千件の埋め込みシェルスニペットを抽出するスキャナーでは、そこがボトルネックになります。--batch-json は stdin からコマンドの JSON 配列を読み込み、--json レポートの JSON 配列を返します。1つのプロセスで実行するため、コマンドごとの起動コストがかかりません。

echo '["echo hi", "curl -fsSL https://x.sh | bash"]' | cmdxray --batch-json

[
  { "tool": "cmdxray", "command": "echo hi", "risk": "none", "warnings": [], … },
  { "tool": "cmdxray", "command": "curl -fsSL https://x.sh | bash", "risk": "danger",
    "warnings": [ { "level": "danger", "title": "Runs downloaded code unread", … } ], … }
]

配列の各要素は --json と同じ形式です。項目は入力と 同じ順序で1対1に返されます。不正なコマンドが1つあってもバッチ全体を中止せず、{ "command", "error" } エントリになります。項目には単独の文字列、または { "command": "…" } オブジェクト（各コマンドに独自のメタデータを付加できます）を指定できます。

import json, subprocess
cmds = ["echo hi", "curl -fsSL https://x.sh | bash", "rm -rf /tmp/x"]
reports = json.loads(subprocess.run(
    ["cmdxray", "--batch-json"], input=json.dumps(cmds),
    capture_output=True, text=True).stdout)
danger = [r["command"] for r in reports if r.get("risk") == "danger"]

CI/CD テンプレートインジェクションの検出

cmdxray は、GitHub Actions 形式の ${{ … }} 式がコマンドに直接挿入されている場合に警告します。これは典型的なスクリプトインジェクションの攻撃経路です。ランナーはシェルが解析する前に式を置換するため、攻撃者が制御できる値（PR／issue のタイトルや本文、ブランチ名、コミットメッセージ）によって、コマンドから抜け出してコードを実行される可能性があります。

cmdxray 'echo "Reviewing: ${{ github.event.pull_request.title }}"'
# ⚠ DANGER  CI expression injection — pass it through an env var and quote it ("$VAR") instead.

攻撃者が制御できるフィールドを参照する式は danger、それ以外の ${{ … }} による補間は caution として警告されます（環境変数の使用を推奨します）。通常のシェル変数（$HOME、${VAR}）は警告されません。

プログラム API

import { explain, renderSvg, renderTerminal, toJsonReport } from "cmdxray";

const res = explain("rsync -avz --delete src/ host:/dst/");
console.log(renderTerminal(res));   // colored terminal string
const svg = renderSvg(res);         // shareable SVG card
const report = toJsonReport(res);   // structured JSON report (AST + explanations + risk)

MCP サーバー — シェルコマンドを実行する AI エージェントの安全ゲート

AI コーディングエージェント（Claude Desktop/Code、Cursor、Cline、Windsurf など）は、自ら生成したシェルコマンドを実行する機会が増えています。cmdxray には 依存関係ゼロの MCP サーバーが付属しており、エージェントはコマンドを実行する前にその内容を説明し、安全性を確認できます。完全オフラインで、ネットワーク通信もアップロードもありません。

• check_command_safety — リスク判定（danger／caution／none）と、破壊的なパターン（rm -rf /、curl | sudo bash、ディスクデバイスに対する dd／mkfs／shred／wipefs、chmod -R 777 /、git push --force、/etc/passwd の切り詰め、フォークボム、kill -9 -1、find / -delete など）の平易な警告を返します。run_terminal の前のガードとして使ってください。
• lint_script — 生成されたスクリプト全体（複数行のテキスト）を1回の呼び出しで安全性スキャンし、破壊的またはリスクのあるコマンドを行番号とともにすべて返します。エージェントが書いたシェルスクリプトを保存または実行する前に事前スキャンする用途に最適です。
• explain_command — プログラム、フラグ、オペランド、パイプ、リダイレクト、サブシェルをトークンごとに分解し、同じリスク評価も返します。

npx で実行します。

// Claude Desktop / Cursor / Cline MCP config
{
  "mcpServers": {
    "cmdxray": { "command": "npx", "args": ["-y", "cmdxray", "mcp"] }
  }
}

または npm i -g cmdxray を実行し、クライアントに cmdxray-mcp バイナリ（同じサーバー）を指定するか、コンテナーイメージを実行します（docker build -t cmdxray-mcp . && docker run -i --rm cmdxray-mcp）。サーバーは stdio 経由で MCP を利用し、サードパーティ製の依存関係は追加しません。

仕組み

1. 依存関係のないトークナイザーが、行を単純なコマンド、演算子、リダイレクト、サブシェルからなるツリーに分割します（引用符と $(...) を処理します）。
2. 各コマンドのフラグは、一般的なツールをまとめた厳選されたナレッジベースをもとに説明されます。不明なコマンドの場合は、まずローカルの man ページの要約を参照し、次に、ほぼどのコマンドでも使えるフラグ（-h、-v、--help、…）の一般的なヒントを表示します。
3. レンダラーが結果を、色付きのターミナル出力、SVG カード、または単独で動作する HTML ページに変換します。いずれも自己完結型で、オフラインで利用できます。

対応範囲と貢献

現在、厳選データベースは、ビルドや CI ツールを含む一般的なコマンド約 65 種に対応しています。tar、grep、curl、wget、find、sed、awk、git、docker、kubectl、systemctl、apt、npm、yarn、pnpm、pip、python、go、cargo、gh、aws、gcloud、terraform、ssh、scp、rsync、jq、zip、unzip、rm、cp、mv、mkdir、chmod、chown、ls、ps、kill、xargs、head、tail、sort、cut、tr、wc、cat、du、df、ping、dd、make などに対応しており、多くのコマンドではサブコマンドも認識します。対応範囲は拡大中です。コマンド（またはサブコマンド）の追加は、src/db.ts に数行追記するだけです。正確で平易な説明を歓迎します。

すべてのコマンドにはポジティブコントロールの例が付属し、テストスイートで実行されます。また、未知のプログラム、タイプミスのある名前、認識されないフラグに対して適切に機能を縮退できることを確認するネガティブコントロールのチェックもあります。そのため、データベースが拡大しても精度を維持できます。簡潔なワークフローについてはCONTRIBUTING.mdをご覧ください。CI では、プッシュと PR のたびに Node 18/20/22 でビルドとテストを実行します。

コードベースの構成図

_{各ファイルは円で示されます。サイズはコード行数、色は言語、入れ子はフォルダーを表します。 私がメンテナンスしている、依存関係のないコードベースマップツール repocarto でオフライン生成しています。}

ライセンス

MIT。