Metadata-Version: 2.4
Name: portui
Version: 0.1.1
Summary: A terminal UI for monitoring and managing local listening ports
Project-URL: Repository, https://github.com/lowtrak/PorTUIi
License: MIT
Requires-Python: >=3.9
Requires-Dist: psutil>=5.9.0
Requires-Dist: textual>=0.52.0
Description-Content-Type: text/markdown

# PorTUI

A terminal UI application for monitoring local listening ports and managing the processes that own them.

## Features

- Real-time display of listening ports with process information
- Configurable columns (Port, IP, Protocol, Process, PID, User, State, Command)
- Sortable by Port, IP, Process, PID, User, State, or Protocol (numerical IP sorting)
- Sort order maintained during auto-refresh
- Inline tree view with real process hierarchy (toggle with `t`) — parent processes are resolved from the OS even when they don't hold ports (e.g. Chrome → Chrome Helper)
- Protocol filter to show TCP only, UDP only, or both (cycle with `h`)
- Real-time text filtering across all fields
- Port detail overlay with full untruncated command line (press Enter, Escape to close)
- Auto-refresh with configurable interval (pauses during interaction)
- Prominent visual indicator when auto-refresh is paused
- Kill processes with choice of graceful (SIGTERM) or force (SIGKILL)
- Cross-platform (macOS, Linux, Windows)

## Installation & Usage

### Run without installing (recommended)

```bash
uvx portui
```

### Install globally

```bash
uv tool install portui
portui
```

### Install with pip

```bash
pip install portui
portui
```

### Run from source

```bash
uv run portui.py
```

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `↑/↓` or `j/k` | Navigate rows |
| `Enter` | Show full port/process details |
| `/` | Focus filter input (Escape to clear and exit) |
| `h` | Cycle protocol filter (Both → TCP → UDP) |
| `c` | Toggle column configuration |
| `s` | Cycle sort column (Port → IP → Process → PID → User → State → Protocol) |
| `t` | Toggle tree view (htop-style process hierarchy) |
| `x` | Kill selected process |
| `r` | Manual refresh |
| `p` | Pause/resume auto-refresh |
| `i` | Set refresh interval |
| `?` | Show help |
| `q` | Quit |

## Requirements

- Python 3.9+
- [uv](https://docs.astral.sh/uv/) (for `uvx` usage)
