PortDoctor

A powerful, cross-platform CLI tool for port and process management with advanced task manager capabilities. Detect, kill, and monitor both ports and processes with an intuitive interface, smart safety features, and beautiful visualizations.

⭐ If you find this tool helpful, please consider giving it a star on GitHub!

Features

Port Management

• Smart Detection - Automatically finds processes using specific ports
• Multiple Port Operations - Kill multiple ports or port ranges at once
• Interactive Mode - Visual selection interface for choosing ports to kill
• Watch Mode - Continuously monitor and auto-kill processes on a port
• Port Listing - View all ports currently in use
• Port Presets - Quick commands for common development ports

Process Management (NEW in v3.0.0)

• Process Listing - View all processes with CPU, RAM, GPU usage
• Resource Monitoring - Real-time system and process monitoring
• Smart Safety - Prevents killing critical system processes
• Process Tree - Visualize process hierarchies
• High-Usage Detection - Find and kill resource-intensive processes
• Pattern Matching - Kill processes by name with wildcard support
• Export & Reports - Generate JSON/CSV reports of processes

General

• Safe Termination - Confirms before killing (unless forced)
• Action Logging - Keeps a history of all operations
• Beautiful Output - Color-coded messages and formatted tables
• Cross-Platform - Works seamlessly on Windows, macOS, and Linux

Installation

Global Installation

npm install -g portdoctor

Use with npx (No Installation Required)

npx portdoctor <port>

Quick Start

Port Management

# Kill a single port
portdoctor 3000

# List all ports in use
portdoctor list

# Interactive mode
portdoctor interactive

# Kill multiple ports
portdoctor 3000,8080,5000 --force

# Kill port range
portdoctor 3000-3010 --force

# Watch a port
portdoctor watch 3000

# Kill common dev ports
portdoctor dev --force

Process Management

# List all processes
portdoctor process list

# List only user processes
portdoctor process list --user

# Sort by memory usage
portdoctor process list --sort memory --top 10

# Get detailed process info
portdoctor process info 1234

# Kill a process safely
portdoctor process kill 1234

# Kill high-usage processes
portdoctor process kill-high --cpu 80 --memory 2048

# Kill processes by name
portdoctor process kill-name "node*" --force

# Real-time monitoring
portdoctor process monitor

# Show process tree
portdoctor process tree --user

# Export processes
portdoctor process export --json

Port Commands

Single Port

Kill a process using a specific port:

portdoctor 3000
portdoctor 3000 --force          # Skip confirmation
portdoctor 3000 --silent         # No logging
portdoctor 3000 -f -s            # Combined options

Multiple Ports

Kill processes on multiple ports at once:

portdoctor 3000,8080,5000
portdoctor 3000,8080,5000 --force

Port Range

Kill all processes in a port range:

portdoctor 3000-3010
portdoctor 8000-8100 --force

List All Ports

Display all ports currently in use:

portdoctor list

Interactive Mode

Select ports to kill from a visual list:

portdoctor interactive
portdoctor interactive --force   # Skip final confirmation

Watch Mode

Continuously monitor a port and auto-kill any process that uses it:

portdoctor watch 3000

Port Info

Get detailed information about a process using a port:

portdoctor info 3000

Generate Report

Export port usage information:

portdoctor report --json         # JSON format
portdoctor report --csv          # CSV format

Dev Preset

Kill common development ports (3000, 8080, 5000, 4200, 8000, 9000):

portdoctor dev
portdoctor dev --force

Process Commands

List Processes

View all processes with resource usage:

portdoctor process list                    # All processes
portdoctor process list --user             # User processes only
portdoctor process list --sort cpu         # Sort by CPU
portdoctor process list --sort memory      # Sort by memory
portdoctor process list --top 10           # Top 10 processes
portdoctor process list --filter "node"    # Filter by name

Process Info

Get detailed information about a specific process:

portdoctor process info 1234

Output includes:

• Process name, PID, parent PID, user
• CPU, memory, GPU usage
• Command line and executable path
• Open ports
• System process indicator
• Safety status

Kill Process

Safely kill a process by PID:

portdoctor process kill 1234
portdoctor process kill 1234 --force

Note: System-critical processes are protected and cannot be killed.

Kill High-Usage Processes

Kill processes consuming excessive resources:

portdoctor process kill-high                      # Default: CPU > 50%, Memory > 1GB
portdoctor process kill-high --cpu 80             # CPU > 80%
portdoctor process kill-high --memory 2048        # Memory > 2GB
portdoctor process kill-high --cpu 70 --memory 1500 --force

Kill by Name Pattern

Kill processes matching a name pattern (supports wildcards):

portdoctor process kill-name "node*"
portdoctor process kill-name "python*" --force
portdoctor process kill-name "*server*"

Real-Time Monitoring

Monitor processes in real-time:

portdoctor process monitor                    # Default: 2s interval, top 10
portdoctor process monitor --interval 1000    # 1s refresh
portdoctor process monitor --top 20           # Show top 20

Press Ctrl+C to exit.

Process Tree

Visualize process hierarchies:

portdoctor process tree              # All processes
portdoctor process tree --user       # User processes only
portdoctor process tree --pid 1234   # Highlight specific PID

Export Processes

Export process information to a file:

portdoctor process export --json              # JSON format
portdoctor process export --csv               # CSV format
portdoctor process export --json --user       # User processes only
portdoctor process export --json --output my-processes.json

Safety Features

PortDoctor includes comprehensive safety measures to prevent system crashes:

• System Process Protection: Maintains a whitelist of 40+ critical Windows/Unix processes
• Path Validation: Checks executable paths (System32, Windows, /sbin, etc.)
• User Validation: Identifies system users (NT AUTHORITY\SYSTEM, root, etc.)
• PID Range Checks: Protects very low PIDs (< 100 on Windows, < 10 on Unix)
• Immutable Protection: Even with --force flag, system processes cannot be killed
• Clear Warnings: Displays detailed reasons when processes cannot be killed

Protected Processes Include:

• Windows: System, csrss.exe, lsass.exe, svchost.exe, dwm.exe, explorer.exe, etc.
• Unix/Linux: init, systemd, kthreadd, launchd, etc.

Command Reference

Port Commands

portdoctor [ports] [options]              Kill single/multiple ports or range
portdoctor list                           List all ports in use
portdoctor interactive [options]          Interactive port selection
portdoctor watch <port>                   Watch and auto-kill on port
portdoctor info <port>                    Show detailed process info
portdoctor report [--json|--csv]          Generate port usage report
portdoctor dev [options]                  Kill common dev ports

Process Commands

portdoctor process list [options]         List all processes
portdoctor process info <pid>             Show detailed process info
portdoctor process kill <pid>             Kill a specific process
portdoctor process kill-high [options]    Kill high-usage processes
portdoctor process kill-name <pattern>    Kill by name pattern
portdoctor process monitor [options]      Real-time monitoring
portdoctor process tree [options]         Show process hierarchy
portdoctor process export [options]       Export process information

Options

-f, --force        Force kill without confirmation
-s, --silent       Silent mode (no logs)
-V, --version      Output version number
-h, --help         Display help

Examples

Example 1: Clean Development Environment

# Kill all common dev ports at once
portdoctor dev --force

Example 2: Find Resource Hogs

# List top 10 processes by CPU
portdoctor process list --sort cpu --top 10

# Kill processes using > 80% CPU
portdoctor process kill-high --cpu 80 --force

Example 3: Monitor Specific Application

# Find node processes
portdoctor process list --filter "node"

# Get detailed info
portdoctor process info 1234

# Monitor in real-time
portdoctor process monitor

Example 4: Clean Up Stuck Processes

# Kill all node processes
portdoctor process kill-name "node*" --force

# Kill all python processes
portdoctor process kill-name "python*" --force

Example 5: System Audit

# Export all processes
portdoctor process export --json

# Show process tree
portdoctor process tree --user

# List all ports
portdoctor list

Log History

PortDoctor maintains a history of all operations:

• Windows: C:\Users\<username>\.portdoctor\history.log
• macOS/Linux: ~/.portdoctor/history.log

Log Format

[11/6/2025, 2:30:45 PM] Killed PID 12345 on port 3000 (node)
[11/6/2025, 3:15:22 PM] Killed PID 67890 (node.exe - CPU: 85.2%, Mem: 512MB)

How It Works

Port Detection

• Windows: netstat -ano + tasklist
• macOS/Linux: lsof -i

Process Management

• Uses systeminformation package for cross-platform metrics
• Real-time CPU, memory, GPU monitoring
• Process tree hierarchy mapping
• Smart safety validation

Termination

• Windows: taskkill /F
• macOS/Linux: kill -9

Requirements

• Node.js >= 18.0.0

Use Cases

• Free up ports blocked by crashed development servers
• Quickly restart services during development
• Find and kill resource-intensive processes
• Monitor system resource usage in real-time
• Clean up stuck or zombie processes
• Audit running processes and port usage
• Automate port/process clearing in build scripts
• Troubleshoot port conflicts in CI/CD pipelines
• Generate reports for system analysis
• Visualize process relationships

Troubleshooting

Permission Denied

If you get "Permission denied" errors:

• Windows: Run as Administrator
• macOS/Linux: Use sudo portdoctor ...

Process Cannot Be Killed

If a process cannot be killed:

• Check if it's a system process (protected for safety)
• Verify you have sufficient permissions
• Try running with elevated privileges

GPU Monitoring Not Available

GPU usage per process is not always available:

• Requires NVIDIA/AMD GPU monitoring tools
• May not be supported on all systems
• Will show "N/A" when unavailable

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please read our Contributing Guidelines for more details.

Contributors

Thanks to all contributors who have helped make PortDoctor better!

License

MIT © Mahesh Sharan

Links

• GitHub Repository
• npm Package
• Report Issues
• Changelog

Support

If you find this tool helpful, please:

• ⭐ Star the repository on GitHub
• 🐛 Report bugs and request features via Issues
• 📢 Share it with other developers
• 💬 Follow @MaheshSharan for updates