splain
A command‑line tool that explains what a shell command will do before you run it.
It parses the command, inspects the filesystem, analyzes flags, pipes, globs, and redirections, and produces a clear, human‑readable explanation — without executing anything.
splain acts as a safety net for your terminal, a teaching tool for shell newcomers, and a static analyzer for complex commands.
✨ Features
- Natural‑language explanations of shell commands
- Filesystem simulation to detect deletes, overwrites, moves, and copies
- Globbing, variable expansion, pipes, and redirection analysis
- Deep analyzers for common commands (
rm,cp,mv,tar,grep,find, etc.) - Man‑page extraction for unknown commands
- Risk detection for destructive patterns
- JSON output mode for editor or script integration
- Zero execution — splain never runs the command
🧠 Why splain exists
Shell commands are powerful but easy to misread or misunderstand. A single typo can delete the wrong directory or overwrite important files. splain helps you understand commands before trusting them.
It’s useful for:
- learning shell commands
- reviewing scripts
- preventing mistakes
- understanding pipelines
- auditing third‑party tools
🔍 How it works
Parsing
splain parses the command into a structured representation:
- program
- flags
- arguments
- pipes
- redirections
- globs
- subshells
- environment variables
Filesystem inspection
splain checks:
- whether paths exist
- whether they’re files, directories, or symlinks
- permissions
- potential overwrites
- how many files a recursive command would affect
Command analyzers
For well‑known commands, splain includes deep semantic analyzers:
- rm
- cp
- mv
- mkdir
- rmdir
- chmod
- chown
- tar
- grep
- find
- head / tail
- cat
- echo
Unknown commands
If splain doesn’t recognize a command, it still explains:
- flag meanings (from man pages)
- argument types
- redirections
- pipes
- potential file writes or overwrites
Explanation generation
The structured analysis is turned into readable text or JSON.
🚀 Usage
Basic example
splain rm -rf ~/Downloads
would result in
This command will recursively delete any files inside the directory ~/Downloads ignoring write protection.