🎯 Port Killer

A comprehensive Node.js CLI tool and library for managing ports and killing processes. Cross-platform support for Windows, macOS, and Linux.

Quick Start: npx @aminventive/port-killer list -s 3000 -e 8000 or npm install -g @aminventive/port-killer

Features

• 🔍 List all open ports with detailed process information
• ⚡ Kill processes by port with graceful termination strategy
• 🎯 Interactive mode for selecting and killing multiple processes
• 🖥️ Cross-platform support (Windows, macOS, Linux)
• 📚 Both CLI and programmatic API
• 🛡️ Graceful termination with SIGTERM → SIGKILL fallback
• 🎨 Colorized output for better user experience
• 🚫 No duplicate entries - Smart deduplication across IPv4/IPv6
• 📊 Accurate port filtering - Precise range filtering on all platforms
• ⚡ Fast performance - Shows only LISTENING processes (servers)

🚀 Installation & Quick Start

Option 1: Use without installing (Recommended for first try)

# Try it instantly with npx
npx @aminventive/port-killer list -s 3000 -e 8000
npx @aminventive/port-killer interactive

Option 2: Global Installation (Recommended for regular use)

npm install -g @aminventive/port-killer

# Now use anywhere
port-killer list -s 3000 -e 8000
pk i  # Interactive mode

Option 3: Local Project Installation (For programmatic usage)

npm install @aminventive/port-killer

System Requirements

• Node.js: 14.0.0 or higher
• OS: Windows, macOS, or Linux
• Permissions: May require elevated permissions for system processes

CLI Usage

List all processes on ports

# List all processes
port-killer list

# Short alias
pk ls

# List processes in specific port range
port-killer list --start 3000 --end 8000
# Short flags available
port-killer list -s 3000 -e 8000

# Filter by protocol
port-killer list --protocol tcp
port-killer list -p tcp

# JSON output
port-killer list --json

Kill process on specific port

# Kill process on port 3000
port-killer kill 3000

# Force kill (skip graceful termination)
port-killer kill 3000 --force

# Custom timeout for graceful termination
port-killer kill 3000 --timeout 10000

Interactive mode

# Launch interactive mode
port-killer interactive

# Short alias
pk i

# Interactive mode with port range
port-killer interactive --start 3000 --end 8000
# Short flags and alias
pk i -s 3000 -e 8000

Kill all processes (use with caution)

# Kill all processes (with confirmation)
port-killer kill-all

# Force kill all without confirmation
port-killer kill-all --force

# Kill all in specific range
port-killer kill-all --start 3000 --end 5000

CLI Options

| Option | Description | Default | |--------|-------------|---------| | -s, --start <port> | Start port range | 1 | | -e, --end <port> | End port range | 65535 | | -p, --protocol <protocol> | Protocol filter (tcp, udp, both) | both | | -f, --force | Force kill without graceful termination | false | | -t, --timeout <ms> | Timeout for graceful termination | 5000 | | -i | Interactive mode (alias for interactive command) | - | | --json | Output as JSON (list command only) | false |

Programmatic API

Import

// ES6/TypeScript
import { getProcessesOnPorts, killProcessOnPort, PortScanner, ProcessKiller } from '@aminventive/port-killer';

// CommonJS
const { getProcessesOnPorts, killProcessOnPort } = require('@aminventive/port-killer');

Convenience Functions

import { getProcessesOnPorts, getProcessOnPort, killProcessOnPort } from '@aminventive/port-killer';

// Get all processes on ports
const processes = await getProcessesOnPorts();
console.log(processes);

// Get specific process on port
const process = await getProcessOnPort(3000);
if (process) {
  console.log(`Process ${process.processName} is running on port 3000`);
}

// Kill process on port
const success = await killProcessOnPort(3000);
if (success) {
  console.log('Process killed successfully');
}

Class-based API

import { PortScanner, ProcessKiller } from '@aminventive/port-killer';

const scanner = new PortScanner();
const killer = new ProcessKiller();

// Scan for processes
const processes = await scanner.getProcessesOnPorts({
  startPort: 3000,
  endPort: 8000,
  protocol: 'tcp'
});

// Kill multiple processes
const result = await killer.killMultipleProcesses(processes, {
  force: false,
  timeout: 5000
});

console.log(`Killed: ${result.killed.length}, Failed: ${result.failed.length}`);

Advanced Usage

import { PortScanner, ProcessKiller, ProcessInfo } from '@aminventive/port-killer';

const scanner = new PortScanner();
const killer = new ProcessKiller();

// Custom port scanning
async function findNodeProcesses(): Promise<ProcessInfo[]> {
  const allProcesses = await scanner.getProcessesOnPorts();
  return allProcesses.filter(p => 
    p.processName.toLowerCase().includes('node') ||
    p.command.toLowerCase().includes('node')
  );
}

// Kill processes with custom logic
async function killDevelopmentServers() {
  const processes = await findNodeProcesses();
  const devProcesses = processes.filter(p => 
    p.port >= 3000 && p.port <= 9000
  );
  
  if (devProcesses.length === 0) {
    console.log('No development servers found');
    return;
  }
  
  console.log(`Found ${devProcesses.length} development servers`);
  const result = await killer.killMultipleProcesses(devProcesses);
  
  console.log(`Successfully killed ${result.killed.length} processes`);
  if (result.failed.length > 0) {
    console.log(`Failed to kill ${result.failed.length} processes`);
  }
}

killDevelopmentServers().catch(console.error);

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import { ProcessInfo, PortKillOptions, PortScanOptions } from '@aminventive/port-killer';

interface ProcessInfo {
  pid: number;
  port: number;
  protocol: string;
  processName: string;
  command: string;
  state?: string;
}

interface PortKillOptions {
  timeout?: number;
  signal?: 'SIGTERM' | 'SIGKILL';
  force?: boolean;
}

interface PortScanOptions {
  startPort?: number;
  endPort?: number;
  protocol?: 'tcp' | 'udp' | 'both';
}

Examples

Development Workflow

# Check what's running on common dev ports
pk ls -s 3000 -e 9000

# Kill your React dev server
pk kill 3000

# Interactive cleanup of all dev servers
pk i -s 3000 -e 9000

One-liner Examples

# Quick port check without installing
npx @aminventive/port-killer list -s 80 -e 80

# Kill process on port 3000 (React dev server)
npx @aminventive/port-killer kill 3000

# Interactive mode for port cleanup
npx @aminventive/port-killer i -s 3000 -e 8000

CI/CD Integration

// cleanup.js - Clean up ports before tests
const { killProcessesInRange } = require('@aminventive/port-killer');

async function cleanupPorts() {
  console.log('Cleaning up development ports...');
  const result = await killProcessesInRange(3000, 9000);
  console.log(`Cleaned up ${result.killed.length} processes`);
}

cleanupPorts().catch(console.error);

Docker Integration

# Kill processes that might conflict with Docker
pk kill 3000 5432 6379 27017

Error Handling

The library includes comprehensive error handling:

import { killProcessOnPort } from '@aminventive/port-killer';

try {
  const success = await killProcessOnPort(3000);
  if (!success) {
    console.log('No process found on port 3000');
  }
} catch (error) {
  console.error('Failed to kill process:', error.message);
}

Platform Compatibility

| Platform | Port Discovery | Process Killing | Notes | |----------|---------------|-----------------|-------| | Windows | netstat + tasklist | taskkill | Full support with IPv4/IPv6 deduplication | | macOS | lsof | kill | Full support | | Linux | lsof + netstat | kill | Full support |

Recent Improvements

• v1.0.0: Fixed Windows port range filtering (--start/--end now work correctly)
• v1.0.0: Eliminated duplicate entries on Windows (IPv4/IPv6 deduplication)
• v1.0.0: Shows only LISTENING processes for cleaner output
• v1.0.0: All commands support short flags (-s, -e, -p, -i)

Permissions

Some operations may require elevated permissions:

• Windows: May need to run as Administrator for system processes
• macOS/Linux: May need sudo for processes owned by other users

🛠️ Development

Local Development

git clone https://github.com/Aminventive/port-killer.git
cd port-killer
npm install
npm run build
npm link  # For global testing

Contributing

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

📈 Stats

• Zero dependencies in production (only dev dependencies)
• TypeScript for type safety
• Cross-platform - Works on Windows, macOS, Linux
• Fast - Shows only relevant LISTENING processes
• Clean - No duplicate entries

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by port-kill desktop application
• Built with modern Node.js and TypeScript best practices
• Cross-platform compatibility using native system commands

Made with ❤️ by Raine Sanchez