cmdxray 是一个离线 shell 命令分析与安全检测工具，由 AI 智能体自主编写、测试和发布，定位是 AI 智能体执行 shell 命令前的安全门。它的核心目标是让用户或智能体在运行命令之前，先看清命令里每个参数、管道、重定向和子 shell 的含义，并识别其中真正具有破坏性的部分。所有处理都在本地完成，不上传任何内容。
主要能力
- 命令标注：解析管线结构（管道、&&、||、重定向、子 shell、组合短选项如 -xzvf），将每个 token、子命令、标志及其取值翻译为通俗英语。支持 git commit、docker run、kubectl get、systemctl restart 等子命令，能把参数值与对应选项关联（如 -p 8080:80、-o out.html）。对常见单行命令如 sed、awk、jq 过滤器以及 ffmpeg、openssl 的多字符单横线选项也能正确解析。对未收录的命令，会读取本机 man page 摘要作为补充，匹配本地实际安装的版本。
- 风险检查：标记命令中真正具有破坏性的部分，例如 curl … | bash、rm -rf /（含 --no-preserve-root）、dd of=/dev/…、mkfs、向磁盘设备重定向、fork bomb、chmod 777、git push --force、git reset --hard、sudo 等，同时对普通安全命令保持安静，避免误报。
- 可分享卡片：生成自包含的 SVG 或 HTML 卡片，可用于 PR 评论、运行手册、幻灯片或社交分享。也可生成链接，在离线浏览器 playground 中打开预加载命令的解析结果。
- lint 门禁：对 shell 脚本、Dockerfile、CI YAML 的 run: 步骤、Makefile、git hook 等文件进行扫描，发现危险命令时使构建失败。输出 file:line 格式的报告，发现 DANGER 时退出码为 1，干净时为 0。--strict 会对 CAUTION 级别也报失败，--exit-zero 只报告不失败，--json 输出机器可读结果。还能检测 GitHub Actions 工作流 run: 块中的 ${{ }} 注入点。
- guard 交互式防护：安装后，当交互式 shell 中即将执行被标记为破坏性的命令时，shell 会暂停并解释危险原因，等待确认；回答 N 则命令不会执行。设计为 fail-open：普通命令不会调用 cmdxray，若 cmdxray 缺失或出错，命令正常执行。目前支持 bash，zsh guard 暂未提供。
- check 风险检查：对单条命令运行危险引擎，以退出码表示结果（0 无危险，1 有风险），便于在脚本中组合使用。
- JSON 输出与批量模式：--json 输出稳定的纯 JSON 报告，包含解析后的 AST、逐 token 解释和风险警告，方便接入自定义工具链。--batch-json 从 stdin 读取 JSON 命令数组，一次进程返回对应的 JSON 报告数组，适合批量扫描仓库中提取出的数千条 shell 片段。
- MCP 服务器：提供零依赖的 MCP 服务器，接入 Claude Desktop/Code、Cursor、Cline、Windsurf 等 AI 智能体，使其在执行命令前可调用 check_command_safety、lint_script、explain_command 三个工具进行安全检查和解释。可通过 npx、全局安装或容器镜像运行，使用 stdio 通信。
使用方式
- 终端运行：cmdxray <command>，逐项标注每个 token。
- 生成卡片：cmdxray -o card.svg "<command>"，或使用 --svg / --html。
- 生成分享链接：cmdxray --link tar -xzvf a.tgz | pbcopy。
- 风险检查：cmdxray check "<command>"。
- 文件扫描：cmdxray lint，可配置为 pre-commit hook 或 GitHub Actions 步骤。
- 交互式防护：在 ~/.bashrc 中添加一行即可启用 guard。
- JSON 与批量：cmdxray --json、cmdxray --batch-json。
- MCP 服务器：npx cmdxray-mcp，或 npm i -g cmdxray 后指向 cmdxray-mcp，或使用 docker build -t cmdxray-mcp . && docker run -i --rm cmdxray-mcp。
适用场景
- 在运行不熟悉的安装脚本或一行命令前，快速理解其行为与风险。
- 在文档、PR、运行手册中分享命令的清晰解释。
- 在 CI 或 pre-commit 阶段阻止危险命令进入代码库。
- 为自主运行 shell 命令的 AI 智能体提供执行前的安全门。
- 批量分析代码库中嵌入的 shell 片段。
限制说明
- lint 是启发式、按行扫描，并非完整 shell 解析器，但危险规则精度较高。
- 命令数据库目前覆盖约 65 个常用命令，仍在增长；未收录命令会回退到本地 man page 或通用提示，因此解释可能不如收录命令详细。
- guard 目前仅支持 bash，zsh guard 暂未提供。
- 关于定价、收费、平台、效果、使用步骤等未在资料中明确提供的信息，本文不作说明。
