unplug

An interactive terminal UI for viewing and killing processes listening on TCP ports. Pure Bash, no dependencies, cross-platform.

Why

Finding what's running on a port usually means piecing together lsof, grep, awk, and kill. unplug replaces that workflow with a single command and an interactive interface.

Features

• Browse all listening TCP processes in a scrollable, color-coded table
• Select one or multiple processes and kill them with a single keypress
• Cross-platform: uses lsof on macOS, ss on Linux (with lsof fallback)
• Pure Bash 3.2+ — works on stock macOS, no Homebrew or dependencies required
• Alternate screen buffer — your terminal is restored cleanly on exit

Install

# Download to your PATH
mkdir -p ~/bin
curl -o ~/bin/unplug https://raw.githubusercontent.com/dannydel/unplug/main/unplug
chmod +x ~/bin/unplug

# Ensure ~/bin is on your PATH (add to ~/.zshrc or ~/.bashrc)
export PATH="$HOME/bin:$PATH"

Or just clone and symlink:

git clone https://github.com/dannydel/unplug.git
ln -s "$(pwd)/unplug/unplug" ~/bin/unplug

Usage

unplug            # launch the TUI
unplug --help     # show help
unplug --version  # show version

Run with sudo to see processes owned by all users:

sudo unplug

Keybindings

Key	Action
Up / Down	Navigate the process list
Space	Toggle selection on the current row
a	Select / deselect all
k	Kill selected processes (SIGTERM)
K	Force kill selected processes (SIGKILL)
r	Refresh the process list
q / Esc	Quit

If no processes are explicitly selected, k and K target the highlighted row. A confirmation prompt is shown before any kill.

Example

 unplug v1.0.0                               12 listening processes

 SEL  PORT    PID      COMMAND                  USER
 [ ]  3000    48210    node                     daniel
 [ ]  5028    15819    dotnet                   daniel
 [x]  5432    1120     postgres                 _postgres
 [x]  8080    52341    python3                  daniel
 [ ]  8828    36182    Code Helper (Plugin)     daniel

 Killed 2 process(es)
 Up/Down:Navigate  Space:Select  a:All  k:Kill  K:Force  r:Refresh  q:Quit

How It Works

• macOS: Parses lsof -iTCP -sTCP:LISTEN -nP -F pcun (machine-readable format) for reliable extraction of PID, command, user, and port — even when process names contain spaces or ports use IPv6.
• Linux: Parses ss -tlnp for listening sockets, resolves usernames via ps. Falls back to lsof if ss is unavailable.
• TUI: Built with ANSI escape codes and tput for cursor control, alternate screen buffer, and color. Input is handled in raw mode via read -rsn1 with escape sequence decoding for arrow keys.

Requirements

• Bash 3.2 or later (ships with macOS)
• lsof (macOS, most Linux distros) or ss (Linux)
• A terminal emulator that supports ANSI escape codes (virtually all of them)

License

MIT