cmdxray

cmdxray is an offline shell command analysis and security detection tool, autonomously written, tested, and released by an AI agent. It is positioned as a security gate before an AI agent executes shell commands. Its core goal is to let users or agents see clearly, before running a command, the meaning of every argument, pipe, redirection, and subshell in the command, and to identify the parts that are truly destructive. All processing is done locally, and nothing is uploaded.

Main capabilities

1. Command annotation: parses pipeline structure (pipes, &&, ||, redirection, subshells, combined short options such as -xzvf), and translates every token, subcommand, flag, and its value into plain English. Supports subcommands such as git commit, docker run, kubectl get, and systemctl restart, and can associate argument values with their corresponding options (such as -p 8080:80, -o out.html). It can also correctly parse common one-line commands such as sed, awk, and jq filters, as well as multi-character single-dash options for ffmpeg and openssl. For commands not included, it reads a summary of the local man page as a supplement, matching the version actually installed locally.
2. Risk check: flags the parts of a command that are truly destructive, such as curl … | bash, rm -rf / (including --no-preserve-root), dd of=/dev/…, mkfs, redirection to a disk device, fork bombs, chmod 777, git push --force, git reset --hard, sudo, and so on, while staying quiet for ordinary safe commands to avoid false positives.
3. Shareable cards: generates self-contained SVG or HTML cards that can be used for PR comments, runbooks, slides, or social sharing. It can also generate a link to open the parsed result of a preloaded command in an offline browser playground.
4. lint gate: scans files such as shell scripts, Dockerfiles, run: steps in CI YAML, Makefiles, and git hooks, and fails the build when dangerous commands are found. Outputs a report in file:line format, with exit code 1 when DANGER is found and 0 when clean. --strict also fails on CAUTION level, --exit-zero only reports withoutfailing, and --json outputs machine-readable results. It can also detect ${{ }} injection points in run: blocks of GitHub Actions workflows.
5. guard interactive protection: after installation, when a command marked as destructive is about to be executed in an interactive shell, the shell pauses and explains the reason for the danger, waiting for confirmation; if the answer is N, the command will not be executed. It is designed to fail-open: ordinary commands do not invoke cmdxray, and if cmdxray is missing or errors out, the command executes normally. Currently bash is supported; zsh guard is not yet provided.
6. check risk check: runs the danger engine on a single command, using the exit code to indicate the result (0 for no danger, 1 for risky), making it easy to combine in scripts.
7. JSON output and batch mode: --json outputs a stable pure JSON report containing the parsed AST, per-token explanations, and risk warnings, making it easy to integrate into custom toolchains. --batch-json reads a JSON array of commands from stdin and returns the corresponding array of JSON reports in a single process, suitable for batch-scanning thousands of shell snippets extracted from a repository.
8. MCP server: provides a zero-dependency MCP server that connects to AI agents such as Claude Desktop/Code, Cursor, Cline, and Windsurf, so that before executing commands they can call the three tools check_command_safety, lint_script, and explain_command for security checks and explanations. It can be run via npx, a global installation, or a container image, using stdio communication.

Usage

• Run in the terminal: cmdxray <command>, annotating each token item by item.
• Generate a card: cmdxray -o card.svg "<command>", or use --svg / --html.
• Generate a share link: cmdxray --link tar -xzvf a.tgz | pbcopy.
• Risk check: cmdxray check "<command>".
• File scan: cmdxray lint, which can be configured as a pre-commit hook or a GitHub Actions step.
• Interactive protection: in ~/.bashrc Add one line to enable guard.
• JSON and batch: cmdxray --json, cmdxray --batch-json.
• MCP server: npx cmdxray-mcp, or npm i -g cmdxray and then point to cmdxray-mcp, or use docker build -t cmdxray-mcp . && docker run -i --rm cmdxray-mcp.

Use cases

• Quickly understand the behavior and risks of an unfamiliar install script or one-liner before running it.
• Share clear explanations of commands in documentation, PRs, and runbooks.
• Prevent dangerous commands from entering the codebase during CI or the pre-commit stage.
• Provide a safety gate before execution for AI agents that autonomously run shell commands.
• Batch-analyze shell snippets embedded in a codebase.

Limitations

• lint is heuristic and scans line by line; it is not a full shell parser, but the dangerous-rule precision is high.
• The command database currently covers about 65 commonly used commands and is still growing; commands not included fall back to local man pages or generic prompts, so explanations may be less detailed than for included commands.
• guard currently supports only bash; zsh guard is not yet available.
• Information not explicitly provided in the materials, such as pricing, charges, platforms, effects, and usage steps, is not explained in this article.