cmdxray

# cmdxray

[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/aurelio-nakamura/cmdxray/badge)](https://scorecard.dev/viewer/?uri=github.com/aurelio-nakamura/cmdxray)
[![npm](https://img.shields.io/npm/v/cmdxray)](https://www.npmjs.com/package/cmdxray)
[![cmdxray MCP server](https://glama.ai/mcp/servers/aurelio-nakamura/cmdxray/badges/score.svg)](https://glama.ai/mcp/servers/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.

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

![cmdxray annotating a command in the terminal](docs/demo.gif)

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

![example card — grep -rn TODO src | head -20, annotated](docs/example.svg)

*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>"`.*

```sh
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:

```sh
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**](https://aurelio-nakamura.github.io/cmdxray/danger/)
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:

```sh
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](#cicd-template-injection-detection)
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:

```yaml
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

```yaml
- 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 /`

![cmdxray guard intercepting rm -rf --no-preserve-root / in the terminal and asking for confirmation](docs/guard.gif)

*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`:

```sh
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:

```sh
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

```sh
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
```

![example card](docs/example.svg)

## Usage

```
cmdxray <command...>            explain a command in your terminal
cmdxray --svg <command...>      emit a shareable SVG card to stdout
cmdxray --html <command...>