Overview

Introduction to kport

kport (or port-killer) is a standalone, single-binary network port inspector and process termination utility written in Rust. It was built to eliminate the tedious cycles of running lsof -i :3000, parsing process IDs manually, and invoking kill -9.

💡 Core Design Principles:

Zero Subshells: Reads kernel socket structures directly instead of spawning sub-processes.
Contextual Awareness: Identifies frameworks (Next.js, Vite, Postgres, Redis) and process working directories.
Safe by Default: Graceful SIGTERM escalation before SIGKILL and daemon protection safeguards.

Installation

kport is distributed across all major package managers:

Universal Shell Script (Linux & macOS)

curl -sSf https://raw.githubusercontent.com/neuralshyam/kport/main/install.sh | sh

Cargo (Rust Crates.io)

cargo install kport

NPM / Bun (Zero-Install Execution)

bunx @neuralshyam/kport 3000
# or globally
bun add -g @neuralshyam/kport

Homebrew (macOS / Linux)

brew install neuralshyam/tap/kport

Arch Linux AUR

yay -S kport-bin

Quick Start

After installation, both port-killer and kport commands are available on your system path.

# 1. Kill a blocking port
kport 3000

# 2. Launch interactive terminal UI
kport

# 3. List active ports in table format
kport --list

Single & Multi-Port Termination

Pass one or more port numbers directly as arguments. kport resolves their active processes and terminates them cleanly:

# Terminate process on port 3000
kport 3000

# Terminate multiple ports simultaneously
kport 3000 8080 5432 6379

# Skip graceful SIGTERM and send SIGKILL immediately
kport 3000 --force

Port Ranges & Wildcards

Manage microservice clusters and container port maps easily using range expressions and wildcard prefixes:

# Range syntax (inclusive)
kport 3000..3010
kport 8080-8085

# Wildcard prefix matching
kport 80*      # Matches 80, 8080, 8000, 8081...
kport 54*      # Matches 5432, 5435...

Dev & DB Presets

Use built-in presets to sweep common development ports without memorizing port numbers:

`kport :dev`

Sweeps web dev servers:

3000, 3001, 5173, 8000, 8080, 4200, 8888, 5000

`kport :db`

Sweeps database servers:

5432 (Postgres), 3306 (MySQL), 6379 (Redis), 27017 (Mongo)

Live HTTP / TCP Prober

Send a lightweight non-blocking probe to verify service health, latency, HTTP status, server header, and HTML <title> without opening a browser:

kport probe 3000
# or
kport --probe 3000

🔍 PROBE REPORT: Port 3000

────────────────────────────────────────

TCP Sockets: OPEN (Active Listener)

Latency: 0.94 ms

HTTP Status: HTTP/1.1 200 OK

Server: Next.js (Vercel)

HTML Title: "Acme Cloud Portal"

Zombie / Orphan Process Sweeper

When an IDE, terminal tab, or Docker container crashes unexpectedly, background Node or Python processes often become orphans (PPID == 1), hogging RAM and blocking ports.

# Scan and terminate all orphaned processes holding ports
kport --zombies

Kill & Exec Chaining

Free a port and immediately spawn your development server in the same terminal session:

kport 3000 --exec "bun dev"
kport 5173 --exec "npm run dev"
kport 8000 --exec "cargo run"

Structured JSON Output

Pass --json with --list to get machine-readable output for integration with scripts, CI pipelines, or editor extensions:

kport --list --json | jq '.[] | select(.port == 3000)'

Interactive TUI Keybindings

Run kport with no arguments to launch the Ratatui interactive dashboard:

Key	Action
↑ / ↓ or j / k	Navigate active port list
/	Live fuzzy search by port, process, framework, or CWD
p	Send live HTTP/TCP probe to selected port
Space	Toggle selection for multi-process batch actions
Enter	Terminate selected process(es) with graceful SIGTERM
K (Shift + K)	Force kill selected process(es) with SIGKILL
r	Refresh socket list
q / Esc	Exit TUI

Monorepo Config (kport.toml)

Place a kport.toml in the root of your project or monorepo to standardize dev port management across team members:

# kport.toml
[services]
frontend  = 3000
backend   = 8000
database  = 5432
redis     = 6379
storybook = 6006

# Check active/down status of all configured services
kport status

# Reset and free all project ports in one command
kport reset

Kernel Socket Architecture & Safety

kport avoids the heavy latency of spawning shell pipelines like lsof or netstat by directly parsing native kernel structures:

Linux: Scans /proc/net/tcp, /proc/net/tcp6, /proc/net/udp and matches socket inodes directly against /proc/<pid>/fd/*.
macOS: Uses native libproc and low-overhead lsof -F record streams.
Windows: Direct Win32 socket table inspection.
Graceful Escalation: Sends SIGTERM and monitors process exit for up to 500ms before falling back to SIGKILL.
Daemon Guard: Rejects termination of system processes (PID ≤ 1, sshd, systemd, dockerd) unless explicitly overridden with --force.