Metadata-Version: 2.4
Name: devports
Version: 0.1.0
Summary: See what's running on your local ports
Project-URL: Homepage, https://github.com/Ltbltbltbltb/devports
Project-URL: Repository, https://github.com/Ltbltbltbltb/devports
Project-URL: Issues, https://github.com/Ltbltbltbltb/devports/issues
Author-email: Lucas <lucastrba2@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,devtools,docker,monitoring,ports,services,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# devports

**See what's running on your local ports.**

[![PyPI](https://img.shields.io/pypi/v/devports)](https://pypi.org/project/devports/)
[![Python](https://img.shields.io/pypi/pyversions/devports)](https://pypi.org/project/devports/)
[![License](https://img.shields.io/github/license/Ltbltbltbltb/devports)](https://github.com/Ltbltbltbltb/devports/blob/main/LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/Ltbltbltbltb/devports/ci.yml?label=CI)](https://github.com/Ltbltbltbltb/devports/actions)

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](LICENSE)
