explainshell

Files (3)

• SKILL.md
• index.ts
• skill.json

SKILL.md (first lines)

# ExplainShell — Shell Command Explainer

Paste any shell command or one-liner and get a plain-English breakdown of every flag, argument, and pipe stage. Powered by explainshell.com, which maps commands to their man-page descriptions.

**No API key required.** Works immediately for any user.

## When to Use

- User pastes a cryptic command and asks "what does this do?"
- Reviewing an unfamiliar bash script or automation pipeline
- Learning: user wants to understand each part of a complex one-liner
- Documentation: need to annotate shell commands in runbooks
- User asks "explain this command", "what does this flag mean?", "break this down"

## How to Use

### Explain a single command (browser link)

```powershell
# The simplest approach — open the explanation in the browser
$command = "tar -xzf archive.tar.gz -C /tmp"
$encoded = [Uri]::EscapeDataString($command)
Start-Process "https://explainshell.com/explain?cmd=$encoded"
Write-Host "Opened: https://explainshell.com/explain?cmd=$encoded"
```

### Fetch explanation text directly (PowerShell)

```powershell
$command = "find . -type f -name '*.log' -mtime +7 -exec rm {} \;"
$encoded = [Uri]::EscapeDataString($command)
$url     = "https://explainshell.com/explain?cmd=$encoded"

$html    = Invoke-WebRequest -Uri $url -UseBasicParsing
# Extract helptext spans (plain text explanations)
$pattern = '<span class="helptext">(.*?)</span>'
$matches = [regex]::Matches($html.Content, $pattern, 'Singleline')

Write-Host "Command: $command"
Write-Host ""
$matches | ForEach-Object {
    $text = $_.Groups[1].Value -replace '<[^>]+>', '' -replace '&amp;', '&' -replace '&lt;', '<' -replace '&gt;', '>'
    if ($text.Trim()) { Write-Host "  • $($text.Trim())" }
}
Write-Host ""
Write-Host "Full explanation: $url"
```

### Explain a piped one-liner

```powershell
$command = "ps aux | awk '{print \$2, \$11}' | sort -k2 | uniq -c | sort -rn | head -10"
$encoded = [Uri]::EscapeDataString($command)
Write-Host "ExplainShell link:"
Write-Host "  https://explainshell.com/explain?cmd=$encoded"
```

## Examples

**"Explain: tar -xzf file.tar.gz"**
→ `tar`: archive utility; `-x`: extract; `-z`: filter through gzip; `-f`: use archive file.

**"What does find . -type f -exec rm {} \\; do?"**
→ `find`: search; `.`: starting directory; `-type f`: only files; `-exec rm {} ;`: run rm on each result.

**"Break down: awk '{print $2}' | sort | uniq -c"**
→ `awk`: text processor prints second field; `sort`: lexicographic sort; `uniq -c`: count consecutive duplicates.

**"What is 2>&1 in a command?"**
→ Redirects stderr (fd 2) to the same destination as stdout (fd 1) — merges error output.

## Cautions

- explainshell.com covers most standard POSIX and GNU commands — may not know custom scripts or aliases
- Very long one-liners (> 200 chars) may produce incomplete explanations
- Some compound expressions (e.g. complex `awk` programs) parse partially
- Rate-limit: be polite — avoid bulk automated requests to a free community service
- The HTML structure may change; if parsing fails, the URL is always valid as a fallback

## Requirements

- None — no API key needed
- Works with any POSIX/GNU shell command or pipeline

From taracodlabs/aiden, Apache-2.0.

More from taracodlabs/aiden