explain-

README

💡 explain

Understand the command before you run it.
A lightweight, zero-dependency, 100% offline CLI tool written in Go that breaks down complex terminal commands, explains their flags, and highlights safety risks before you run them.

---

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.
• Interactive Safe Runner: Use explain -i to paste complex pipelines without quotes, or explain -r "<command>" to execute with confirmation.

---

Safety & Hazard Detection

---

Installation

Option 1: One-Line Installer (Recommended)

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

Option 2: Go Install

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

Option 3: Build from Source

git clone https://github.com/Yehya-Elsawy/explain-.git
cd explain
make
make install

---

📖 CLI Usage

USAGE:
  explain <command with arguments>
  explain "<piped | or compound command>"
  explain -i (interactive mode - no quotes needed)

OPTIONS:
  -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 explain version
  -h, --help        Show help message

---

Shell Integration (Bonus)

Add this alias to your ~/.bashrc or ~/.zshrc to quickly explain your last executed terminal command:

alias explain-last='explain "!!" '

---

🤝 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.