Live TUI
Open ports with no arguments for a live table of listeners that refreshes every
3 seconds.
ports v2.0.0
See what is running on your machine’s ports, fast.
ports gives developers a live terminal UI and quick CLI commands for
inspecting listeners, spotting the project behind them, identifying the framework,
and acting immediately without hopping across half a dozen system commands on macOS, Linux, or
Windows.
ports opens the interactive TUIports list --json feeds scripts and tooling~/dev/ports
ports v2.0.0 [all ports] [port asc]
Tracking 5 listening ports. Auto-refresh every 3s.
PORT PROJECT FRAMEWORK PID MEM UPTIME COMMAND
>3000 web-app Next.js 18421 312.4
MB 02:18:44 node
4321 astro-docs Astro 18803 146.8 MB 00:44:10 node
5173 vite-dashboard Vite 19022 229.1
MB 01:12:59 node
5432 postgres - 1127 82.5 MB 2-03:17:48 postgres
11434 ollama - 2281 654.7 MB
1-09:52:11 ollama
╭────────────────────────────────────────────────────────────────────────────╮
│ Selected │
│ Port 3000 · web-app · PID 18421 │
│ Framework Next.js · Mem 312.4 MB · Uptime 02:18:44 │
│ /Users/dev/projects/web-app │
╰────────────────────────────────────────────────────────────────────────────╯
[↑/↓] Move [/] Search [f] Filter [s] Sort [K] Kill [o] Open URL [e]
Open Editor [r] Refresh [q] Quit
Features
Project Awareness
Walks upward to package.json to identify the project name and detect frameworks
like Next.js, Astro, Vite, Remix, Nuxt, SvelteKit, and Angular.
Useful Signals
Shows port, project, framework, PID, memory, uptime, and command, while visually dimming system processes so dev servers stand out.
Fast Actions
Kill a listener, open its localhost URL, or jump directly into the detected project folder in your preferred editor from the TUI.
Filters, Sorting, Search
Focus on dev ports, node-like processes, high-memory listeners, long-running services, or a specific project or port instantly.
Script Friendly
Use ports list --json to pipe the data into your own scripts, shell workflows,
dashboards, or tooling.
How To Use It
Interactive TUI
ports
Launch the live terminal interface with refresh, filtering, sorting, search, and keyboard actions.
Static Table
ports list
Print the listening ports table once and exit.
JSON Output
ports list --json
Return a JSON array of port records with port, pid,
command, projectName, framework,
memoryKB, and uptime.
Inspect One Port
ports check 3000
See detailed information about a single port, or confirm that it is free.
Stop A Listener
ports kill 3000
Attempt a graceful stop first, wait 1 second, and then force-stop the process if it refuses to exit.
Keyboard Shortcuts
↑/↓
Move through the current list
/
Open search and filter by project, command, or port
f
Cycle filters: all ports, dev ports, node only
s
Cycle sort modes: port, memory, uptime, project
K
Kill the selected process
o
Open http://localhost:PORT in your browser
e
Open the detected project folder in your preferred editor
r
Refresh immediately
How It Works
- On macOS and Linux,
portsuseslsofandpsto discover listeners, working directories, memory usage, uptime, and command labels. - On Windows,
portsuses PowerShell built-ins likeGet-NetTCPConnectionandGet-CimInstance Win32_Process. - The tool then normalizes that process data into one shared model so the same TUI, CLI, and JSON output work across platforms.
- It walks upward from the detected working directory or best-guess project path until it finds
package.json. - Dependencies are inspected to detect frameworks and improve the context shown in the UI.
Tech Stack
TypeScript
Core implementation and type safety.
Commander.js
CLI argument parsing and subcommands.
Ink
React-powered terminal UI.
chalk
Color and visual emphasis in terminal output.
execa
Reliable execution of system commands.
tsup
Fast TypeScript bundling for the CLI binary.
PowerShell
Windows listener and process discovery via built-in commands.
lsof + ps
macOS/Linux listener, cwd, command, memory, and uptime discovery.
Get Started
npm install
npm run build
npm link
ports
After npm link, you can run ports from anywhere on your machine.
In non-interactive shells it automatically falls back to a static list view.
The e shortcut uses PORTS_EDITOR, then VISUAL, then
EDITOR, and finally code if it is available.