faahh

Play dramatic meme audio whenever a command fails in your terminal.

Install

npm install -g faahh
# or
bun add -g faahh
# or
pnpm add -g faahh

Quick Start

faah init
source ~/.zshrc # or ~/.bashrc / ~/.config/fish/config.fish

Failed commands (exit code != 0) now trigger sound. Ctrl+C (130) is ignored.

Usage

faah                 # Interactive action dashboard
faah init            # Install shell hook (zsh, bash, fish)
faah verify          # Check audio player, assets, and hook status
faah play            # Test sound playback
faah enable          # Turn alerts on
faah disable         # Mute alerts
faah settings        # Interactive settings (volume, cooldown, quiet hours, detection, patterns)
faah preset quiet    # Apply a preset (balanced, quiet, aggressive)
faah snooze 30       # Mute alerts for 30 minutes ("faah snooze clear" to resume)
faah run -- npm test # Run a command and alert on error output patterns
faah update          # Check for CLI updates on npm
faah version         # Print installed version
faah uninstall       # Remove shell hooks

Commands & Aliases

| Command | Aliases | Description | | ---------------- | ------------------------------- | ------------------------------------------------------------------------ | | faah | — | Interactive action dashboard | | faah init | setup, install, i | Install shell hook (.zshrc, .bashrc, config.fish) | | faah uninstall | remove, rm, unlink | Remove error listener hooks | | faah verify | status, check, doctor | Inspect audio player, sound assets, hook status | | faah play | test, sound | Play alert sound directly | | faah settings | config, cfg, conf, pref | Manage every setting (get, set, list, export, import, reset) | | faah preset | presets, mode | Apply a settings preset (balanced, quiet, aggressive) | | faah snooze | silence | Snooze alerts for N minutes, or clear to resume | | faah run | wrap | Run a command, alert on error output patterns | | faah enable | on, unmute | Enable terminal error alerts | | faah disable | off, mute | Disable / mute alerts | | faah version | v, ver | Print installed version | | faah update | upgrade | Check for updates on npm |

Flags

faah init --shell zsh             # Target specific shell (zsh, bash, fish)
faah init --all                   # Install into all detected shells
faah play --sound /path/to/file   # Play custom audio file (.wav, .mp3)
faah play --blocking              # Wait for audio to finish
faah play --force                 # Play even when disabled, snoozed, or in quiet hours
faah play --ignore-config         # Bypass quiet hours / cooldown
faah settings export faah.json    # Export settings (same schema as the VS Code extension)
faah settings import faah.json    # Import settings, invalid regexes rejected

Detection Modes

faah settings set terminalDetectionMode <mode>

• either (default): shell hook alerts on non-zero exit, faah run also matches output patterns
• exitCode: only non-zero exit codes alert
• output: only output patterns alert (use faah run -- <command>)

Patterns, exclude patterns, exclude presets and pattern mode are shared with the VS Code extension, so faah settings export / import move settings between both.

Audio Backends

• macOS: afplay (native)
• Linux: paplay / ffplay / mpv / mpg123 / mpg321 / cvlc / mplayer / sox / aplay
• Windows: PowerShell MediaPlayer (volume aware), SoundPlayer at 100%

License

MIT © Toufiq Hasan Kiron