ports-cli

Interactive TUI for viewing and killing listening TCP ports on macOS and Linux.

---

Demo

Quick Start

Run it directly with npx -- no install required:

npx ports-cli

Or install globally:

npm install -g ports-cli

Then run:

ports

Features

• Real-time monitoring -- port list auto-refreshes every 2 seconds
• Interactive search -- filter by port number, address, PID, or process name
• Kill processes -- terminate processes with a confirmation prompt, or skip it with ctrl+k
• Vim-style navigation -- j/k to move, g/G to jump to first/last
• IPv6 normalization -- [::1] maps to 127.0.0.1, [::] maps to 0.0.0.0, deduplicating entries
• Viewport scrolling -- adapts to terminal height, keeps selection visible
• Help overlay -- press ? for a full keybinding reference
• Zero config -- no flags, no setup, just run it

Keybindings

Key	Action
↑ / k	Move selection up
↓ / j	Move selection down
g / G	Jump to first / last
enter / x	Kill selected process (with confirmation)
ctrl+k	Kill selected process (skip confirmation)
/	Enter search mode
ESC	Clear search / cancel
r / R	Refresh port list
?	Toggle help overlay
q / ctrl+c	Quit

Options

ports --help, -h       Show help
ports --version, -v    Show version

How It Works

ports-cli runs lsof -iTCP -sTCP:LISTEN -nP to discover all processes listening on TCP ports. The raw output is parsed, deduplicated, and normalized (converting IPv6 loopback and wildcard addresses to their IPv4 equivalents). The result is rendered as a full-screen terminal UI using Ink, a React renderer for the terminal. The list refreshes automatically every 2 seconds. Killing a process sends SIGKILL to the target PID.

Requirements

• macOS or Linux -- requires lsof (pre-installed on macOS; install via apt install lsof or dnf install lsof on Linux)
• Node.js >= 18

Contributing

git clone https://github.com/patebry/ports-cli.git
cd ports-cli
npm install

Development commands:

npm run build        # Compile to dist/ports.js
npm run typecheck    # TypeScript type checking
npm run lint         # ESLint
npm test             # Run test suite (189 tests)
npm run coverage     # Run tests with coverage report

Built with TypeScript, React 18, Ink 4, esbuild, and Vitest.

License

MIT