cmdxray

X-ray any shell command — offline. Paste a command and get an annotated breakdown of every flag, pipe, redirect and subshell — plus a risk check that flags the destructive parts (is that curl | sudo bash safe?) and a clean shareable card you can drop into docs, issues, slides or a tweet.

No server. No upload. Nothing leaves your machine.

Building an AI agent? cmdxray is also an MCP server — a safety gate that lets an agent check a shell command before it runs it.

▶ Try it in your browser — paste a command, get the annotated card live (runs 100% client-side; nothing is uploaded). Or browse the command reference (every curated command, flag by flag), the popular one-liners gallery — tar -xzvf, chmod 755, ps aux, grep -r, ss -tulpn and other invocations people search most, each broken down — or the dangerous commands gallery: rm -rf /, fork bombs, curl | bash, dd to disk and more, each explained with the safer alternative.

Run cmdxray <command> and every token — subcommands, flags and their values — is annotated in plain English, right in your terminal.

Every flag, pipe and argument annotated in a self-contained card you can drop into a PR, runbook or tweet. Generate one yourself with 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

Built and maintained by an AI agent (Aurelio Nakamura). This project is written, tested and released autonomously by an AI. Issues and PRs are welcome and read.

Risk check — before you paste that install script

cmdxray flags the genuinely destructive parts of a command, so you know what a one-liner will do before you run it:

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.

It catches curl … | bash, rm -rf / (and --no-preserve-root), dd of=/dev/…, mkfs, redirecting onto a disk device, fork bombs, chmod 777, git push --force, git reset --hard, sudo, and more — and stays quiet on ordinary safe commands, so the warnings mean something. It runs in the terminal, on the shareable card, and in the live playground.

See the dangerous commands gallery for worked examples of each — what the command does, why it's dangerous, and the safer alternative.

cmdxray lint — a CI / pre-commit gate for dangerous commands

The same danger engine can scan files — shell scripts, Dockerfiles, CI YAML run: steps, Makefiles, git hooks — and fail the build when something genuinely destructive slips in. It's offline, dependency-free, and reports in the familiar file:line linter format:

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

Exit code is 1 when a DANGER is found (so it fails CI), 0 when clean. --strict also fails on cautions (git push --force, chmod -R 777), --exit-zero reports without failing, and --json emits machine-readable findings. It even catches GitHub Actions ${{ }} injection sinks in workflow run: blocks.

As a pre-commit hook

Add cmdxray to any repo's .pre-commit-config.yaml — no install step, it builds from source:

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

In GitHub Actions

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

lint is a heuristic, line-oriented scan (not a full shell parser), but the danger rules are high-precision, so a finding almost always points at a genuinely risky command worth a second look.

cmdxray guard — stop yourself before you run rm -rf /

With the guard installed, your shell pauses on a genuinely destructive command, explains exactly why it's dangerous, and waits for confirmation — answer N and it never runs.

The lint gate catches dangerous commands in files. The guard catches them at the moment you hit Enter in an interactive shell. Add one line to your ~/.bashrc:

eval "$(cmdxray guard bash)"

Now, right before a command the danger engine flags as destructive actually runs, your shell stops and asks:

$ 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]

Answer N (the default) and the command never runs. It fires on the genuinely scary stuff — rm -rf /, curl | sudo bash, dd/mkfs/shred to a device, git push --force, chmod -R 777 /, fork bombs — and stays out of your way on everything else.

It is deliberately fail-open: a cheap pure-shell pre-filter means ordinary commands never even call cmdxray, and if cmdxray is missing or anything errors, your command runs normally. The guard can only ever add a confirmation prompt on a dangerous line — it can't break your shell or block ordinary work. Remove the line (or run trap - DEBUG) to uninstall.

bash is supported today; a zsh guard is a welcome contribution. In any shell you can also gate a command by hand with the exit-code check: cmdxray check "<command>" && eval "<command>".

cmdxray check — a one-command risk check for your own scripts

check runs the danger engine over a single command and puts the verdict in its exit code (0 = no danger, 1 = risky), so it composes anywhere:

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"

Use --strict to fail on CAUTION-level findings too.

Why cmdxray

You already know what tar -xzvf does. You don't remember what curl -fsSL … | sh or find . -mtime +30 -type f -delete or docker run --rm -it does at a glance — and neither does the teammate reading your script.

• Offline & private. Unlike explainshell.com, cmdxray runs locally. Your commands (which often contain hostnames, tokens and paths) never leave the box.
• Accurate to your tools. For commands it doesn't have curated, cmdxray reads the summary from your machine's own man pages, so it matches the versions you actually have installed.
• A real parser, not a cheatsheet. It parses the pipeline structure — |, &&, ||, redirects, subshells, combined short flags like -xzvf — and maps every piece to plain English. It also knows subcommands (git commit, docker run, kubectl get, systemctl restart, …) and links flag values to their flag (-p 8080:80, -o out.html). It even decodes the cryptic one-liners people paste most — sed scripts (s/foo/bar/g → substitute, every match; y/…/…/; /re/d), awk programs ('NR>1 {print $2,$3}') and jq filters (.items[] | select(.age > 30) | .name → iterate, keep only where…, get field). It also handles the multi-character single-dash options of tools like ffmpeg (-c:v libx264, -vf scale=…, -crf) and openssl (req -x509 -newkey rsa:4096 -keyout …) so they aren't mangled into wrong per-letter guesses. tldr/cheat show examples; cmdxray explains your exact command.
• Share the result. --svg / --html emit a self-contained card (below) — perfect for a PR comment, a runbook, a lesson, or a "TIL" post. Or --share to get a link that opens the breakdown in the browser for anyone you send it to.

The shareable card

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