devports 0.1.0

See what's running on your local ports

devports

See what's running on your local ports.

A developer-friendly CLI that scans your local ports, identifies what's running on each one, checks service health, and displays everything in a clean terminal table.

                          Local Services
 ---------------------------------------------------------------
  PORT  | SERVICE              | STATUS          | ADDRESS
 ---------------------------------------------------------------
  3000  | next-dev             | ● healthy (3ms) | 127.0.0.1
  5173  | vite                 | ● healthy (1ms) | 127.0.0.1
  5432  | postgres   [docker]  | ● healthy (2ms) | 0.0.0.0
  6379  | redis      [docker]  | ● healthy (1ms) | 0.0.0.0
  8000  | fastapi              | ● healthy (5ms) | 127.0.0.1
  8080  | api-server           | ● down          | 0.0.0.0
  9090  | prometheus [docker]  | ● healthy (4ms) | 0.0.0.0
 ---------------------------------------------------------------
 7 service(s) found

Features

• Port scanning -- discovers all listening TCP ports via ss
• Service identification -- maps ports to friendly names using a built-in database of 30+ common services, process name matching, and command-line analysis
• Docker integration -- detects Docker containers and tags them accordingly
• Health checking -- probes each port with a TCP connection and reports healthy/down/unknown with response time in milliseconds
• JSON output -- structured output for scripting and piping
• Live watch mode -- auto-refreshing view that updates as services start and stop
• Open in browser -- launch a service by port number or name
• Kill by port -- terminate a process by the port it listens on
• PID and command display -- optional columns showing process IDs and full command lines

Installation

pip install devports

Requires Python 3.10+ and a Linux system with ss available (standard on all modern distributions).

Usage

Scan all ports

devports

Show process IDs

devports --pid

Show full command lines

devports --cmd

Skip health checks

devports --no-health

JSON output

devports --json

Returns a JSON array with port, service, pid, process, address, tags, and health information for each entry. Useful for scripting:

devports --json | jq '.[].service'

Live watch mode

devports watch
devports watch --interval 5
devports watch --pid

Auto-refreshing terminal UI. Updates every 2 seconds by default. Press Ctrl+C to stop.

Open a service in the browser

devports open 3000
devports open next-dev

Accepts a port number or a service name (partial match). Uses xdg-open or wslview on WSL.

Kill a process by port

devports kill 8080

Sends SIGTERM to the process listening on the given port.

How It Works

1. Scan -- Reads listening TCP sockets from ss -tlnpH and enriches each entry with data from /proc (command line, process name)
2. Identify -- Matches each port against a known-port database, maps process names to service names, and parses command lines to detect frameworks (Next.js, Vite, FastAPI, Django, Spring, etc.)
3. Docker -- Queries docker ps to match published port bindings to container names and tags them with [docker]
4. Health check -- Opens a TCP connection to each port and measures response time; reports healthy, down, or unknown
5. Display -- Renders a formatted table using Rich, or outputs structured JSON

Service Detection

devports uses four layers to identify what is running on each port:

Layer	Method	Example
Docker containers	docker ps port bindings	postgres container on 5432
Process name map	Match process name to known services	redis-server -> redis
Known port database	30+ common dev ports	5173 -> vite, 9092 -> kafka
Command-line analysis	Parse cmdline for framework keywords	node .../next/... -> next-dev

Layers are evaluated in order. The first match wins.

For generic runtimes like node, python, and java, devports inspects the full command line to detect specific frameworks: Next.js, Vite, Nuxt, Remix, Express, NestJS, Django, Flask, FastAPI, Gunicorn, Jupyter, Spring, and Tomcat.

Contributing

git clone https://github.com/Ltbltbltbltb/devports.git
cd devports
pip install -e ".[dev]"
pytest
ruff check src/

License

MIT