port-audit

A TUI tool for managing TCP listening ports on macOS.

Features

• List all TCP listening ports
• Show process source for each port, using the working directory when useful and the app/process name for macOS app services
• Show process uptime for each port, based on process start time
• Infer how a port was launched, such as from a terminal app, Codex, or another macOS app
• Real-time refresh (every 2 seconds)
• Search filter (by port number, process name, source, or launcher)
• Kill processes (SIGTERM → SIGKILL)
• Tokyo Night theme

Requirements

• Bun runtime (development only)

Installation

Homebrew:

brew install hehehai/tap/port-audit

No Bun runtime is required for the prebuilt binary.

npm:

npm i -g @hehehai/port-audit

macOS only. The npm package ships a prebuilt binary.

npx:

npx portaudit

GitHub Packages:

npm config set @hehehai:registry https://npm.pkg.github.com
npm i -g @hehehai/port-audit

GitHub Release (macOS binary):

curl -L -o port-audit.tar.gz https://github.com/hehehai/port-audit/releases/download/vX.Y.Z/port-audit-vX.Y.Z-macos.tar.gz
tar -xzf port-audit.tar.gz
./port --help

GitHub Release (Linux binary):

curl -L -o port-audit.tar.gz https://github.com/hehehai/port-audit/releases/download/vX.Y.Z/port-audit-vX.Y.Z-linux.tar.gz
tar -xzf port-audit.tar.gz
./port --help

GitHub Release (Windows binary):

curl -L -o port-audit.tar.gz https://github.com/hehehai/port-audit/releases/download/vX.Y.Z/port-audit-vX.Y.Z-windows.tar.gz
tar -xzf port-audit.tar.gz
.\port.exe --help

From source:

bun install
bun link

One-line installer:

curl -fsSL https://raw.githubusercontent.com/hehehai/port-audit/main/scripts/install.sh | sh

Usage

port

For development:

bun run dev:tui

Lint:

bun run lint

Test:

bun run test

CLI

port --help
port list
port list -s 3001
port list -s chrome
port k 3001

port list prints:

PORT   PID    COMMAND    UPTIME   USER     LAUNCHED BY    SOURCE                       NAME
3002   21370  node       1h 2m    guanwei  Ghostty        ~/x/doit/my-app/apps/web     [::1]:3002
9222   644    Google     2d 21h   guanwei  Google Chrome  Google Chrome                127.0.0.1:9222

• UPTIME is the process runtime, derived from the process start time.
• LAUNCHED BY is inferred from the process parent chain. It can identify terminal apps, Codex, or app-backed services when that parent chain is still available.
• SOURCE is the best available source hint. Project services usually show a shortened working directory; app-backed services usually show the app or process name.
• The TUI detail row shows the fuller launch chain when available, such as Ghostty > zsh > pnpm > vite.
• Search matches port, command, user, launcher, source, working directory, executable path, and socket name.

Dev CLI:

bun run cli -- --help

Keybindings

| Key | Action | |---|---| | ↑/k | Move up | | ↓/j | Move down | | / | Search | | esc | Exit search | | x/Enter | Kill process | | r | Refresh | | q | Quit |

Tech Stack

• OpenTUI - Terminal UI framework
• React 19
• Bun