portclear

> Enterprise-grade port management utility for modern development workflows
> Zero dependencies • Cross-platform • Universal language support • Production-ready


---

Table of Contents

- Overview
- Why portclear?
- Installation
- Quick Start
- CLI Reference
- API Documentation
- Universal Language Support
- Advanced Usage
- Platform Compatibility
- Performance & Benchmarks
- Troubleshooting
- Migration Guide
- Contributing
- License

---

Overview

portclear is a lightweight, zero-dependency utility designed to terminate processes occupying specified network ports. Built for modern development workflows, it supports all major operating systems and programming languages, making it an essential tool for developers, DevOps engineers, and system administrators.

$3

| Feature | Description |
|---------|-------------|
| Zero Dependencies | Pure Node.js implementation using only built-in modules |
| Cross-Platform | Windows, macOS, Linux, and Unix systems fully supported |
| Language Agnostic | Works with processes from any programming language |
| Port Ranges | Kill multiple ports simultaneously with range syntax |
| Preview Mode | Inspect processes before termination |
| TypeScript Native | Full type definitions included out of the box |
| Production Ready | Battle-tested with comprehensive error handling |
| Minimal Footprint | ~10 KB package size vs 60-174 KB in alternatives |

---

Why portclear?

$3

``
┌─────────────────────────────────────────────────────────────────┐
│ COMPARISON: portclear vs Alternatives │
├─────────────────┬───────────┬───────────┬───────────┬───────────┤
│ Metric │ portclear │ kill-port │ killport │ port-kill │
├─────────────────┼───────────┼───────────┼───────────┼───────────┤
│ Package Size │ ~10 KB │ ~60 KB │ ~1.5 KB │ ~35 KB │
│ Dependencies │ 0 │ 2 │ 2 │ 0 │
│ TypeScript │ ✓ │ @types │ ✗ │ ✗ │
│ Port Ranges │ ✓ │ ✗ │ ✗ │ ✗ │
│ Preview Mode │ ✓ │ ✗ │ ✗ │ ✓ │
│ JSON Output │ ✓ │ ✗ │ ✗ │ ✗ │
│ Process Tree │ ✓ │ ✗ │ ✗ │ ✓ │
│ Windows Support │ ✓ │ ✓ │ ✗ │ ✓ │
│ Quiet Mode │ ✓ │ ✗ │ ✗ │ ✗ │
│ Active / Latest │ ✓ │ ✗ │ ✗ │ ✗ │
└─────────────────┴───────────┴───────────┴───────────┴───────────┘
`

$3

- Simplicity First: Single-purpose tool that does one thing exceptionally well
- Developer Experience: Intuitive CLI with comprehensive documentation
- Zero Lock-in: No proprietary dependencies or vendor tie-ins
- Enterprise Grade: Production-ready with robust error handling
- Future Proof: Active maintenance and continuous improvements


---




Installation

$3

Use npx for one-time execution without global installation:

`bash
npx portclear 3000
`

$3

Install once, use everywhere:

`bash
npm install -g portclear
`

$3

Add to your project's development dependencies:

`bash
npm install --save-dev portclear
`

`bash
yarn add -D portclear
`

`bash
pnpm add -D portclear
`

$3

For convenience, portclear is published under multiple package names:

| Package Name | Command | Status |
|--------------|---------|--------|
| portclear | npx portclear | Primary (recommended) |
| portstop | npx portstop | Alias |
| pkill-port | npx pkill-port | Alias |
| port-nuke | npx port-nuke | Alias |
| port-eject | npx port-eject | Alias |

> Note: All aliases provide identical functionality. Use whichever name you prefer.


---




Quick Start

$3

`bash


Kill process on port 3000

npx portclear 3000

Kill multiple ports

npx portclear 3000 8080 9000

Kill port range

npx portclear 3000-3010

Preview without killing

npx portclear --list 3000
`

$3

Before Starting Development Server `bash Clean up before npm start npx portclear 3000 npm start `	CI/CD Pipeline `bash Silent cleanup in scripts npx portclear --quiet 3000 || true `
Docker Port Conflicts `bash Free up Docker ports npx portclear 2375 2376 5000 `	Multiple Microservices `bash Clear service port range npx portclear 8000-8010 `

---

CLI Reference

$3

`
portclear [options]
`

$3

| Option | Short | Type | Description |
|--------|-------|------|-------------|
| --port | -p | number | Specify port number (supports ranges and comma-separated lists) |
| --list | -l | boolean | List processes without terminating (preview mode) |
| --method | -m | string | Protocol type: tcp or udp (default: tcp) |
| --verbose | -v | boolean | Display detailed output including PIDs and process names |
| --quiet | -q | boolean | Suppress output (errors only) |
| --json | | boolean | Output results in JSON format |
| --tree | | boolean | Terminate process tree including child processes |
| --from | | number | Start of port range |
| --to | | number | End of port range |
| --help | -h | boolean | Display help information |

$3

Port Range Operations

`bash


Range syntax (dash notation)

portclear 3000-3010

Range syntax (flags)

portclear --from 3000 --to 3010

Mixed ranges and individual ports

portclear 3000-3005 8080 9000

Comma-separated ports

portclear -p 3000,8080,9000
`

Preview Mode (List Without Killing)

`bash


Basic listing

portclear --list 3000

Verbose listing with process details

portclear -l 3000 -v

List port range

portclear --list 3000-3010

JSON output for automation

portclear -l --json 3000
`

Protocol-Specific Operations

`bash


Kill TCP process (default)

portclear 3000

Kill UDP process

portclear -p 5353 -m udp

Kill both TCP and UDP

portclear -p 53 -m tcp && portclear -p 53 -m udp
`

Process Tree Termination

`bash


Kill parent and all child processes

portclear --tree 3000

Useful for processes that spawn workers

portclear --tree 8000 -v
`

Automation & Scripting

`bash


Quiet mode for CI/CD

portclear --quiet 3000

JSON output for parsing

portclear --json 3000 | jq '.ports[0].killed'

Conditional execution

if portclear -q 3000; then
echo "Port cleared successfully"
else
echo "Failed to clear port"
exit 1
fi
`


---




API Documentation

$3

portclear provides a clean, promise-based API for programmatic usage.

#### Basic Usage

`javascript
const portclear = require('portclear');

// Kill process on port 3000
await portclear(3000);
`

#### Advanced Options

`javascript
// Configure with options object
await portclear(3000, {
method: 'tcp', // 'tcp' | 'udp'
list: false, // Preview mode
tree: true // Kill process tree
});

// Backward compatible (v0.x syntax still supported)
await portclear(3000, 'udp');
`

#### TypeScript Support

`typescript
import portclear, { PortClearOptions, PortClearResult } from 'portclear';

// Type-safe configuration
const options: PortClearOptions = {
method: 'tcp',
list: true,
tree: false
};

// Type-safe result handling
const result: PortClearResult = await portclear(3000, options);

if (result.killed) {
console.log(Terminated ${result.name} (PID: ${result.pid}));
}
`

#### Type Definitions

`typescript
interface PortClearOptions {
method?: 'tcp' | 'udp'; // Protocol type
list?: boolean; // Preview mode
tree?: boolean; // Kill process tree
}

interface PortClearResult {
port: number; // Port number
killed: boolean; // Termination status
platform: string; // Operating system
pid?: number; // Primary process ID
pids?: number[]; // All process IDs
name?: string; // Process name
error?: string; // Error message if failed
stdout?: string; // Command output
stderr?: string; // Command errors
listing?: boolean; // Preview mode indicator
}
`

#### Error Handling

`javascript
try {
const result = await portclear(3000);
console.log(Successfully terminated process on port ${result.port});
} catch (error) {
if (error.message.includes('Permission denied')) {
console.error('Insufficient privileges. Try running with sudo.');
} else if (error.message.includes('No process running')) {
console.log('Port is already available.');
} else {
console.error(Unexpected error: ${error.message});
}
}
`

#### Preview Before Termination

`javascript
// Safe operation: preview then terminate
async function safeKill(port) {
// Step 1: List process
const preview = await portclear(port, { list: true });

if (preview.error) {
console.log(Port ${port} is free);
return;
}

console.log(Found: ${preview.name} (PID: ${preview.pid}));

// Step 2: Confirm with user (in interactive mode)
const confirmed = await getUserConfirmation();

// Step 3: Terminate if confirmed
if (confirmed) {
await portclear(port);
console.log('Process terminated successfully');
}
}
`


---




Universal Language Support

portclear operates at the operating system level, making it language-agnostic. It works with processes from any programming language or runtime.

$3



























































Language	Frameworks & Runtimes	Default Ports
JavaScript/TypeScript	Node.js, Deno, Bun, Express, Next.js, React, Vue, Angular dev servers	3000, 3001, 8080
Python	Flask, Django, FastAPI, Streamlit, Jupyter notebooks	5000, 8000, 8888
Go	Gin, Echo, Fiber, net/http	8080, 8000
Java/Kotlin	Spring Boot, Micronaut, Ktor, Tomcat, Jetty	8080, 8081, 9090
Ruby	Rails, Sinatra, Puma, Rack	3000, 4000
PHP	Laravel, Symfony, built-in server	8000, 8080
Rust	Actix, Rocket, Axum, Warp	8000, 3000
C/C++	Any HTTP server, TCP/UDP services	Varies
.NET/C#	ASP.NET Core, Kestrel	5000, 5001
Elixir	Phoenix	4000

$3

portclear doesn't interact with your application code. Instead, it:

1. Queries the operating system for processes using the specified port
2. Identifies the process ID (PID) via platform-specific commands:
- Windows: netstat -ano + taskkill
- Unix/Linux/macOS: lsof -ti + kill
3. Terminates the process using OS-level signals

This approach ensures compatibility with any language or framework that uses network ports.


---




Advanced Usage

$3

#### Express.js Application

`javascript
const portclear = require('portclear');
const express = require('express');

async function createServer(port = 3000) {
try {
// Clean port before starting
await portclear(port, { quiet: true });

const app = express();

// Configure routes
app.get('/', (req, res) => res.send('Hello World'));

// Start server
app.listen(port, () => {
console.log(Server running on http://localhost:${port});
});
} catch (error) {
console.error('Failed to start server:', error.message);
process.exit(1);
}
}

createServer();
`

#### Python Integration

`python
#!/usr/bin/env python3
import subprocess
import sys

def clear_port(port):
"""Clear a port using portclear via subprocess."""
try:
subprocess.run(
['npx', 'portclear', '--quiet', str(port)],
check=True,
capture_output=True
)
return True
except subprocess.CalledProcessError:
return False

Usage in Flask/Django


if __name__ == '__main__':
PORT = 5000

if clear_port(PORT):
print(f'Port {PORT} cleared successfully')

# Start your Flask/Django app
# app.run(port=PORT)
`

#### Package.json Scripts

`json
{
"scripts": {
"clean": "portclear --quiet 3000 8080",
"predev": "npm run clean",
"dev": "next dev",
"prestart": "portclear -q 3000",
"start": "node server.js",
"test": "portclear -q 3001 && jest",
"docker:clean": "portclear 2375 2376 5000-5010"
}
}
`

#### Makefile Integration

`makefile
.PHONY: clean dev prod

clean:
@npx portclear --quiet 3000 8080 || true

dev: clean
@npm run dev

prod: clean
@npm start

test: clean
@npm test
`

#### Docker Compose

`yaml
version: '3.8'
services:
app:
build: .
ports:
- "3000:3000"
command: >
sh -c "npx portclear -q 3000 && npm start"
`

$3

#### Port Range Management

`javascript
// Kill all ports in development range
async function cleanDevPorts() {
const ports = Array.from({ length: 11 }, (_, i) => 3000 + i);

const results = await Promise.allSettled(
ports.map(port => portclear(port, { quiet: true }))
);

const killed = results.filter(r => r.status === 'fulfilled').length;
console.log(Cleaned ${killed} out of ${ports.length} ports);
}
`

#### Graceful Shutdown

`javascript
// Implement graceful shutdown with timeout
async function gracefulKill(port, timeout = 5000) {
try {
// Try normal termination first
await portclear(port);
return true;
} catch (error) {
// If failed, try with process tree
console.log('Attempting force kill with process tree...');
await portclear(port, { tree: true });
return true;
}
}
`

#### Health Check Integration

`javascript
// Health check before starting service
async function healthCheck(port) {
const result = await portclear(port, { list: true });

if (!result.error) {
console.warn(WARN: Port ${port} is already in use by ${result.name});
return false;
}

return true; // Port is free
}
`


---




Platform Compatibility

$3

| Platform | Version | Support Level | Commands Used |
|----------|---------|---------------|---------------|
| Windows | 7, 8, 10, 11, Server | Full | netstat -ano, taskkill /PID /F |
| macOS | 10.12+ | Full | lsof -ti :PORT, kill -9 |
| Linux | All major distributions | Full | lsof -ti :PORT, kill -9 |
| Unix | FreeBSD, OpenBSD | Full | lsof -ti :PORT, kill -9 |

$3

- Minimum Version: Node.js 14.0.0
- Recommended: Node.js 18.0.0 or later
- LTS Support: All current LTS versions

$3

- TCP: Full support (default)
- UDP: Full support (use -m udp flag)
- IPv4: Full support
- IPv6: Depends on OS implementation


---




Performance & Benchmarks

$3

`
Average execution time (single port):
Windows: ~150ms
macOS: ~80ms
Linux: ~70ms

Port range (10 ports):
Sequential: ~800ms
Parallel: ~200ms (implementation dependent)
`

$3

`
Memory: < 15 MB
CPU: Minimal (< 5% during execution)
Disk I/O: Negligible
`

$3

`
Package size: 10.3 KB (packed)
Unpacked size: 33.5 KB
Install time: < 2 seconds
Dependencies: 0
`


---




Troubleshooting

$3

Permission Denied Error

Problem: EACCES: permission denied for port 3000

Solution:

`bash


macOS/Linux

sudo npx portclear 3000

Windows (run PowerShell/CMD as Administrator)

npx portclear 3000
`

Explanation: Some ports (especially < 1024) require elevated privileges on Unix-based systems.

Port Still in Use After Termination

Problem: Port remains occupied after running portclear

Possible Causes:
1. Process takes time to release the port (TIME_WAIT state)
2. Multiple processes using the same port
3. Child processes not terminated

Solutions:

`bash


Solution 1: Wait and verify

portclear -l 3000 # Check if process is gone
sleep 2 # Wait for TCP cleanup
portclear -l 3000 # Verify again

Solution 2: Use process tree kill

portclear --tree 3000

Solution 3: Kill port range

portclear 3000-3002 # Kill related ports
`

Invalid Port Number

Problem: Error: Invalid port number

Valid port range: 1 - 65535

`bash


Invalid

portclear 0 # Too low
portclear 99999 # Too high
portclear abc # Non-numeric

Valid

portclear 3000
portclear 1-65535
`

Command Not Found

Problem: portclear: command not found

Solutions:

`bash


Solution 1: Use npx (no installation needed)

npx portclear 3000

Solution 2: Install globally

npm install -g portclear
portclear 3000

Solution 3: Use in package.json scripts

npm run clean # If configured in scripts
`

$3

For troubleshooting, use verbose mode to see detailed information:

`bash


Enable verbose output

portclear -v 3000

Combine with list mode for inspection

portclear -l -v 3000

JSON output for programmatic debugging

portclear --json 3000 | jq '.'
`

$3

- Documentation: GitHub README
- Issues: GitHub Issues
- npm Package: npmjs.com/package/portclear

---

Migration Guide

$3

`bash


Old (kill-port)

npx kill-port 3000
npx kill-port 3000 3001 3002

New (portclear)

npx portclear 3000
npx portclear 3000 3001 3002

or

npx portclear 3000-3002
`

$3

`bash


Old (killport)

npx killport 3000

New (portclear)

npx portclear 3000

With options

npx portclear --quiet 3000 # Silent mode
npx portclear --list 3000 # Preview mode
`

$3

`bash


Old (fuser)

fuser -k 3000/tcp

New (portclear)

npx portclear 3000
npx portclear -m tcp 3000 # Explicit TCP
`

---

Contributing

We welcome contributions from the community! Here's how you can help:

$3

`bash


Clone repository

git clone https://github.com/mreshank/portclear.git
cd portclear

Install dependencies (none for runtime, dev only)

npm install

Run tests

npm test

Test CLI locally

node cli.js --help
`

$3

1. Code Style: Follow existing patterns and conventions
2. Tests: Add tests for new features
3. Documentation: Update README.md for user-facing changes
4. Commits: Use clear, descriptive commit messages
5. Pull Requests: One feature per PR, include rationale

$3

`bash


Run full test suite

npm test

Test specific port

node cli.js -l 3000

Test with actual process

node test/test.js
``

---

License

MIT License © 2024 Eshank Tyagi

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

---

Acknowledgments

Built with care for the developer community. Special thanks to all contributors and users who have helped improve this tool.

Repository: github.com/mreshank/portclear
npm Package: npmjs.com/package/portclear
Author: Eshank Tyagi • GitHub

---