Building PortPilot: A Modern TUI for Port Management

Ever typed lsof -i :3000 | grep LISTEN for the hundredth time today? Yeah, me too.

I built PortPilot – a terminal UI that shows all listening ports on your machine, lets you kill processes with one key, and detects port conflicts.

The Problem

As a developer juggling multiple services (frontend servers, databases, Redis, Docker containers), I was constantly typing lsof -i to figure out what was running where. The workflow was painful:

1. Type lsof -i :3000 | grep LISTEN
2. Find the PID
3. Type kill -9 <PID>
4. Repeat for the next port

I needed something visual but terminal-native.

The Solution

PortPilot is a Go-based TUI built with Bubble Tea that gives you a real-time dashboard of all listening ports.

Key Features

• 📊 Interactive TUI with real-time updates
• ⚡ One-key process killing (select, press k, confirm, done)
• 🔍 Search/filter by port or process name
• 🚨 Conflict detection (highlights when multiple processes fight for the same port)
• 📋 CLI mode for scripting (portpilot list --json | jq ...)
• 🏷️ Service groups (tag ports as "frontend", "backend", "database")

Tech Stack

• Go (fast, single binary, cross-platform)
• Bubble Tea (Elm-architecture TUI framework)
• Cobra (CLI commands)
• Lip Gloss (styling)

No root required – uses lsof (macOS) or ss (Linux) under the hood.

Installation

go install github.com/AbdullahTarakji/portpilot/cmd/portpilot@latest

Then just run:

portpilot

Usage

TUI Mode

Launch the interactive UI:

portpilot

• Navigate with arrow keys
• Press k to kill a process
• Press / to search
• Press q to quit

CLI Mode

# List all listening ports
portpilot list

# Check a specific port
portpilot check 3000

# Kill a process on a port
portpilot kill 8080

# JSON output for scripting
portpilot list --json | jq '.[] | select(.port == 3000)'

What's Next

• Windows support (using netstat)
• Docker container detection
• Custom port groups
• Export/import configurations

Try It Out

⭐ Star it on GitHub: github.com/AbdullahTarakji/portpilot

Feedback and PRs welcome!

golang #opensource #devtools #cli