port-audit

A TUI tool for managing TCP listening ports on macOS.

Features

• List all TCP listening ports
• Real-time refresh (every 2 seconds)
• Search filter (by port number or process name)
• 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 k 3001

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

Release Automation

GitHub Actions publishes on tags like v0.1.0. Releases include macOS/Linux/Windows binary tarballs used for direct installs.

Required secrets:

• NPM_TOKEN for npm publish
• HOMEBREW_TOKEN for Homebrew tap updates
• HOMEBREW_TAP (e.g. hehehai/tap)
• HOMEBREW_FORMULA (e.g. port-audit)
• GITHUB_TOKEN is used automatically for GitHub Packages publish