aurelio-nakamura/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 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 " ".*
> **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:
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:
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:
In GitHub Actions
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:
Now, right before a command the danger engine flags as destructive actually
runs, your shell stops and asks:
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