explain

README

💡 explain

Understand the command before you run it.

Linux shouldn't feel scary just because a command looks complicated.

explain is a beginner-friendly CLI tool that helps you understand terminal commands, break down their flags, and spot potential risks before you run them. Lightweight, zero-dependency, and 100% offline built with Go.

Enjoy learning Linux more with explain :) .

---

Supported Platforms & Distributions

explain is compiled as a single standalone static binary with zero external dependencies, working seamlessly across:

Architecture	Linux	macOS	Windows (WSL)
x86_64 / amd64 (Intel & AMD)	Supported	Supported (Intel)	Supported
arm64 / aarch64 (Apple Silicon, Raspberry Pi, AWS Graviton)	Supported	Supported (M1/M2/M3/M4)	Supported
i386 / 32-bit	Supported	—	—

---

Why explain?

When beginners copy commands from ChatGPT, StackOverflow, or tutorials, they often don't know what cryptic flags (-xzvf, -laht, -p 8080:80, | sh) actually do.

• Reading full man pages is overwhelming.
• Asking online AI models requires internet access, API keys, and context switching.
• Running commands blindly can lead to accidental data loss (rm -rf, > file, dd).

With explain, you just prepend explain before any command:

explain tar -xzf backup.tar.gz

---

Features

• Zero Dependencies & 100% Offline: Single static binary (<5MB). Instant execution (<5ms) with no network calls or API keys required.
• Smart Flag Decomposition: Unpacks clustered short flags (e.g., -xzvf $\to$ -x, -z, -v, -f) and maps them to their values.
• Shell Builtins & Navigation: Understands cd, pwd, echo, export, alias, clear, and path transitions (.., ~, -).
• Pipeline & Redirect Aware: Understands multi-stage pipelines (ps aux | grep nginx | awk ...) and I/O redirections (>, >>, 2>&1).
• Safety & Danger Meter: Warns against destructive operations (rm -rf /, dd of=/dev/sdX, chmod 777, curl ... | bash).
• Dynamic Man & Help Fallback: Real-time extraction from local man pages and --help for any unlisted command installed on your system.
• Modern & Compact Terminal UI: Beautiful ANSI colors and aligned columns designed to give you everything in 5–8 clean lines.
• Explain Last Command: Explain previous commands effortlessly via explain !! or explain-last.
• Interactive Safe Runner: Use explain -i to paste complex pipelines without quotes, or explain -r "<command>" to execute with confirmation.
• Built-in Self Updater: Run explain update to automatically upgrade to the latest GitHub release.

---

Safety & Hazard Detection

---

Installation & Updating

1. One-Line Installer (Recommended)

Works on any Linux distribution and macOS:

curl -fsSL https://raw.githubusercontent.com/Yehya-Elsawy/explain/main/scripts/install.sh | bash

2. Go Install

go install github.com/Yehya-Elsawy/explain/cmd/explain@latest

3. Updating explain to Latest Release

Whenever a new version is released, simply run:

explain update

4. Uninstalling explain

If you ever wish to remove explain from your system, simply run:

explain uninstall

Or via the one-line uninstaller script:

curl -fsSL https://raw.githubusercontent.com/Yehya-Elsawy/explain/main/scripts/uninstall.sh | bash

---

CLI Usage

USAGE:
  explain <command with arguments>
  explain "<piped | or compound command>"
  explain !! (explain the last executed command)
  explain update (auto-update to latest release)
  explain uninstall (remove explain from system)
  explain -i (interactive mode - no quotes needed)

EXAMPLES:
  explain tar -xzf backup.tar.gz
  explain cd /home/
  explain !!
  explain "rm -rf /tmp/cache"
  explain "find . -name '*.log' -mtime +30 -delete"
  explain "ps aux | grep nginx | awk '{print $2}' | xargs kill -9"
  explain "curl -fsSL https://get.docker.com | sh"

COMMANDS & OPTIONS:
  explain update    Check and upgrade explain to the latest release from GitHub
  explain uninstall Remove explain CLI from your system
  -i, --interactive Launch interactive mode (paste complex pipelines without quotes)
  -r, --run         Ask to run the command after explaining it
  --json            Output structured analysis in JSON format
  --no-color        Disable colored output
  -v, --version     Show current explain version
  -h, --help        Show this help message

---

Shell Integration (Bonus)

Want to explain the command you just executed without retyping or copying it?

Option 1: Direct Terminal Shortcut (No Setup Needed)

Simply type:

explain !!

---

Option 2: Dedicated explain-last Shortcut (Recommended)

Add this function to your ~/.bashrc (or ~/.zshrc if you use Zsh):

explain-last() {
  local cmd i=1
  while [ $i -le 10 ]; do
    cmd=$(fc -ln -$i -$i 2>/dev/null | sed 's/^[[:space:]]*//')
    [ -z "$cmd" ] && break
    case "$cmd" in
      explain-last*|explain_last*|explain\ !!*)
        i=$((i+1))
        ;;
      *)
        explain "$cmd"
        return
        ;;
    esac
  done
}

Then reload your shell configuration:

source ~/.bashrc   # or: source ~/.zshrc

Now, anytime you run a command and want to inspect what it just did, just type:

cd /var/log
explain-last

---

Contributing

Contributions are welcome! To add support for more commands or flags, feel free to open a Pull Request.

# Run tests
make test

# Build local binary
make build

---

License

Distributed under the MIT License. See LICENSE for details.