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