Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ports-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

ports-cli

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

Demo

ports-cli 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