port-kill

Open source

Port Kill helps you find and free ports and caches blocking your dev work.

2.0K stars0 likes0 views

About

Port Kill helps you find and free ports and caches blocking your dev work.

Port Kill

Port Kill helps you find and free ports blocking your dev work, plus manage development caches and orchestrate services. It works on macOS, Linux, and Windows, locally or over SSH with a simple CLI and status bar.

Two Binaries, Full Feature Parity:

port-kill - GUI status bar app (macOS only) + full CLI
port-kill-console - Pure CLI version (all platforms)

Both binaries support all features including smart restart, service detection, and orchestration.

Community & Support

Join our Discord community for discussions, support, and updates:

Install

bash

# macOS/Linux
curl -fsSL portkill.com/install | bash

# Windows (PowerShell or CMD)
curl -fsSL portkill.com/install-windows -o install-release.bat && install-release.bat

Windows users: After installation, you MUST restart your terminal completely for PATH changes to take effect.

Troubleshooting Windows Installation

If you get 'port-kill' is not recognized error after installing:

Close and reopen your terminal completely (required for PATH changes)

Run diagnostics to identify the issue:

powershell

powershell -Command "Invoke-WebRequest -UseBasicParsing -Uri 'https://raw.githubusercontent.com/treadiehq/port-kill/main/diagnose-installation.bat' -OutFile 'diagnose.bat'"; .\diagnose.bat

Test with full path (works without PATH):

powershell

"%USERPROFILE%\AppData\Local\port-kill\port-kill.exe" --list

See WINDOWS.md for detailed Windows-specific guidance.

Quick start

…

Smart Restart & Service Management (NEW!)

Port Kill now intelligently manages your development server lifecycle:

Smart Restart

Automatically restarts processes using their original startup commands:

bash

# Kill and restart a process (saves restart info automatically)
port-kill 3000                    # Kill process on port 3000
port-kill --restart 3000          # Restart it with saved command

# View restart history
port-kill --show-restart-history  # See all restartable ports

# Clear restart info
port-kill --clear-restart 3000    # Remove saved restart info

Service Detection & Start

Automatically discover and start services from your project:

bash

# Discover available services
port-kill --detect

# Found services examples:
#   npm:dev - npm run dev (Node.js)
#   npm:start - npm run start (Node.js)
#   docker:web - Docker Compose service: web
#   python:app.py - Python app: app.py

# Start a discovered service
port-kill --start npm:dev
port-kill --start docker:web

Supported project types:

npm/yarn/pnpm - Detects package.json scripts
Docker Compose - Detects docker-compose.yml services
Procfile - Detects Procfile processes
Python - Detects app.py, manage.py, etc.

Guard Mode with Auto-Restart

Keep your services running automatically:

bash

# Guard a port and auto-restart if process dies
port-kill --guard 3000 --guard-auto-restart

# Works with reservations
port-kill --guard-mode --guard-auto-restart \
  --reserve-port 3000 \
  --project-name "my-app" \
  --process-name "npm"

Service Orchestration (NEW!)

Manage multiple services together with a simple YAML configuration file.

Quick Start

bash

# 1. Create a configuration file
port-kill --init-config

# 2. Edit .port-kill.yaml to define your services
# (see example below)

# 3. Start all services
port-kill --up

# 4. Check status
port-kill --status

# 5. Stop all services
port-kill --down

Configuration Example

Create .port-kill.yaml in your project root:

yaml

version: "1"

# Global environment variables
env:
  NODE_ENV: development
  DEBUG: "true"

services:
  # Frontend service
  frontend:
    command: npm run dev
    port: 3000
    dir: ./frontend
    startup_delay: 2
    env:
      PORT: "3000"
  
  # Backend API service
  backend:
    command: npm run start
    port: 8000
    dir: ./backend
    depends_on:
      - database
    env:
      PORT: "8000"
      DATABASE_URL: postgres://localhost:5432/myapp
  
  # Database service
  database:
    command: docker-compose up database
    port: 5432
    startup_delay: 5

Orchestration Commands

bash

# Initialize configuration
port-kill --init-config

# Start all services (respects dependencies)
port-kill --up

# Stop all running services
port-kill --down

# Restart a specific service
port-kill --restart-service backend

# Check status of all services
port-kill --status

# Use custom config file
port-kill --config-file my-config.yaml --up

Configuration Options

Service Fields:

command - Command to run the service (required)
port - Port the service runs on (optional)
dir - Working directory for the service (optional)
env - Service-specific environment variables (optional)
depends_on - List of services to start first (optional)
startup_delay - Seconds to wait after starting (optional)
healthcheck - Command to check service health (optional)

Global Fields:

version - Config version (optional)
env - Environment variables for all services (optional)
services - Map of service definitions (required)

Dependency Management

Services start in dependency order:

yaml

services:
  api:
    command: npm start
    depends_on:
      - database
      - redis
  
  database:
    command: docker-compose up database
  
  redis:
    command: redis-server

Start order: database → redis → api

CLI quick reference

…

…

Cache Management

Port Kill now includes comprehensive cache management for development environments:

Cache Commands

bash

# List all detected caches
./target/release/port-kill-console cache --list

# List with JSON output
./target/release/port-kill-console cache --list --json

# Clean caches safely (with backup)
./target/release/port-kill-console cache --clean --safe-delete

# System diagnostics
./target/release/port-kill-console cache --doctor --json

# Restore last backup
./target/release/port-kill-console cache --restore-last

Language-Specific Cache Management

bash

# Rust caches (target/, ~/.cargo)
./target/release/port-kill-console cache --list --lang rust

# JavaScript/TypeScript caches (node_modules, .next, .vite, etc.)
./target/release/port-kill-console cache --list --lang js

# Python caches (__pycache__, .venv, .pytest_cache)
./target/release/port-kill-console cache --list --lang py

# Java caches (.gradle, build, ~/.m2)
./target/release/port-kill-console cache --list --lang java

NPX Package Analysis

bash

# Analyze NPX packages with per-package details
./target/release/port-kill-console cache --npx --list --json

# Clean stale NPX packages (older than 30 days)
./target/release/port-kill-console cache --npx --clean --stale-days 30

# Dry run to see what would be cleaned
./target/release/port-kill-console cache --npx --dry-run --stale-days 14

JavaScript Package Manager Caches

bash

# npm, pnpm, yarn caches
./target/release/port-kill-console cache --js-pm --list --json

# Clean JS package manager caches
./target/release/port-kill-console cache --js-pm --clean --safe-delete

Specialized Integrations

bash

# Hugging Face cache
./target/release/port-kill-console cache --hf --list

# PyTorch cache
./target/release/port-kill-console cache --torch --list

# Vercel cache (requires VERCEL_TOKEN env var)
VERCEL_TOKEN=your_token ./target/release/port-kill-console cache --vercel --clean

# Cloudflare cache (requires CLOUDFLARE_TOKEN env var)
CLOUDFLARE_TOKEN=your_token ./target/release/port-kill-console cache --cloudflare --clean

Safe Operations

All cache operations are safe by default:

Safe delete: Creates timestamped backups before deletion
Restore capability: --restore-last to undo the last cleanup
Dry run: --dry-run to preview changes without executing
Force override: --force to skip confirmations (use with caution)

Dashboard

The dashboard provides real-time process monitoring, system resource tracking, history analytics, and security auditing.

Running the Dashboard Locally

Navigate to the dashboard directory:
bash
```
cd dashboard
```
Install dependencies (first time only):
bash
```
npm install
```
Start the dashboard:
bash
```
npm run dev
```
Open in your browser:
```
http://localhost:3002
```

The dashboard will automatically connect to port-kill and display:

Real-time process monitoring on all ports
System resource usage (CPU, memory, disk)
Process history and analytics
Security audit information
Port guard status

Quick start script:

bash

# From project root - starts dashboard in one command
./run-dashboard.sh

Or on Windows:

powershell

.\run-dashboard.bat

For more details, see the dashboard README.

Check out the full Kill Suite for additional tools and features.

MCP (use Port Kill from Cursor, Claude etc.)

Add npx -y 'https://gitpkg.vercel.app/treadiehq/port-kill/mcp?main' to your MCP config.

Available Tools

Port Management:

list - List processes on ports
kill - Kill processes on ports
reset - Reset common dev ports
audit - Security audit
guardStatus - Port guard status

Cache Management (NEW!):

cacheList - List all detected caches
cacheClean - Clean caches with safe backup
cacheRestore - Restore last cache backup
cacheDoctor - System diagnostics

For example for Cursor add to .cursor/mcp.json:

{
   "mcpServers": {
      "port-kill-mcp": {
         "command": "npx",
         "args": ["-y", "https://gitpkg.vercel.app/treadiehq/port-kill/mcp?main"]
      }
   }
}

Notes:

The server shells out to ./target/release/port-kill-console or port-kill-console if it is on the PATH. If yours lives elsewhere, set PORT_KILL_BIN=/absolute/path/to/port-kill-console. e.g.

{
   "mcpServers": {
      "port-kill-mcp": {
         "command": "npx",
         "args": ["-y", "https://gitpkg.vercel.app/treadiehq/port-kill/mcp?main"],
         "env": {
            "PORT_KILL_BIN": "/absolute/path/to/port-kill-console"
         }
      }
   }
}

See mcp/README.md for more information on port-kill-mcp including how to install from source.

Features

Real‑time process detection on specific ports or ranges
One‑shot cleanup: --reset
Smart filtering and ignore lists
Port Guard Mode (watch/reserve/auto‑resolve)
Security Audit Mode (suspicious ports, risk score, JSON)
Remote Mode over SSH
Works with Docker; console mode works everywhere

Presets

Port Kill supports named presets so you can avoid long --ports lists and reuse common configurations.

Usage:

…

Custom presets:

User-defined presets live at ~/.port-kill/presets.json and override built-ins when names match

Common flags

bash

--ports 3000,8000,8080          # specific ports
--ports '6000-9999'             # port ranges (new!)
--ports '3000,6000-6002,8000'   # mixed individual ports and ranges
--start-port 3000 --end-port 9000
--ignore-ports 5353,5000,7000
--ignore-processes Chrome,rapportd
--guard-mode --auto-resolve
--audit --json
--remote user@server

Manual Installation

Clone the repository:

bash

git clone <repository-url>
cd port-kill

Install and build (recommended):

bash

./install.sh

Or manually:

bash

./build-macos.sh
./run.sh

Linux Installation

Clone the repository:

bash

git clone <repository-url>
cd port-kill

Install required packages:

bash

# Ubuntu/Debian
sudo apt-get install libatk1.0-dev libgdk-pixbuf2.0-dev libgtk-3-dev libappindicator3-dev

# Fedora/RHEL
sudo dnf install atk-devel gdk-pixbuf2-devel gtk3-devel libappindicator-gtk3-devel

# Arch Linux
sudo pacman -S atk gdk-pixbuf2 gtk3 libappindicator-gtk3

Install and build (recommended):

bash

./i

Issues· 0 open

View all issues Open on GitHub

No open issues yet, or sync has not completed.

> Tags

Rust

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026

UpdatedSep 17, 2026

Category编程语言

PricingOpen source

> Related tools

TypeScript

JavaScript 的超集，为前端与全栈提供静态类型

Python

通用编程语言，广泛用于 Web、数据与 AI

Google 推出的简洁高效系统语言

port-kill

About

Port Kill

Community & Support

Install

Troubleshooting Windows Installation

Quick start

Smart Restart & Service Management (NEW!)

Smart Restart

Service Detection & Start

Guard Mode with Auto-Restart

Service Orchestration (NEW!)

Quick Start

Configuration Example

Orchestration Commands

Configuration Options

Dependency Management

CLI quick reference

Cache Management

Cache Commands

Language-Specific Cache Management

NPX Package Analysis

JavaScript Package Manager Caches

Specialized Integrations

Safe Operations

Dashboard

Running the Dashboard Locally

MCP (use Port Kill from Cursor, Claude etc.)

Available Tools

Features

Presets

Common flags

Manual Installation

Linux Installation

Issues· 0 open

> Tags

> Discussion

> Details

> Related tools