⚡ zap

A blazing-fast developer port and process manager for the command line.

zap is a cross-platform CLI tool that helps developers quickly find, list, kill, and monitor network ports and the processes behind them. No more guessing which process is hogging port 3000 — just zap it.

✨ Features

• 🔍 Find which process is using a specific port
• 💀 Kill the process occupying a port with a single command
• 📋 List all listening ports in a clean table
• 👀 Watch ports in real-time to detect new or closed connections
• 🖥️ Cross-platform — works on Windows, macOS, and Linux
• 🎨 Colorful output with chalk for better readability
• ⚡ Fast — built with modern ESM and TypeScript

📦 Installation

npm install -g @anthonyfree96/zap

Or run directly with npx:

npx @anthonyfree96/zap <command>

🚀 Usage

Usage: zap [options] [command]

zap developer port manager

Options:
  -V, --version   output the version number
  -h, --help      display help for command

Commands:
  find <port>     Find which process is using a port
  kill [options] <port>  Kill the process using a port
  list            List all listening ports
  watch           Watch port changes in real-time
  help [command]  display help for command

🔍 Find a process by port

Find out what's running on a specific port:

zap find 3000
zap find 8080

💀 Kill a process by port

Kill the process that's using a specific port:

zap kill 3000
zap kill 8080

Force-kill by default; pass --graceful to terminate gracefully instead.

📋 List all listening ports

Display all currently listening ports in a table:

zap list

Example output:

┌───────┬────────┬──────────┐
│ port  │ pid    │ protocol │
├───────┼────────┼──────────┤
│ 3000  │ 12345  │ tcp      │
│ 5432  │ 67890  │ tcp      │
│ 8080  │ 11111  │ tcp      │
└───────┴────────┴──────────┘

👀 Watch port changes

Monitor ports in real-time — see when new ports start listening or when existing ones close:

zap watch

New connections appear with a green +, closed connections with a yellow -:

Watching ports...
+ port=3000 pid=12345
+ port=8080 pid=11111
- port=3000

🛠️ Development

Prerequisites

• Node.js >= 22.12.0
• npm >= 9

Setup

# Clone the repository
git clone https://github.com/AndyFree96/zap.git
cd zap

# Install dependencies
npm install

# Run in development mode
npm run dev -- <command>

Available Scripts

| Script | Description | | ---------------- | ----------------------------------------- | | npm run dev | Run with tsx (hot-reload for development) | | npm run build | Clean and compile TypeScript | | npm run clean | Remove the dist directory | | npm run lint | Lint with ESLint | | npm run format | Format with Prettier | | npm test | Run unit tests |

Build

npm run build

This compiles TypeScript from src/ to JavaScript in dist/.

🏗️ Project Structure

zap/
├── src/
│   ├── index.ts             # CLI entry point & command definitions
│   ├── commands/
│   │   └── list.ts          # List command implementation
│   └── core/
│       ├── port.ts           # Port lookup (find which process uses a port)
│       ├── process.ts        # Process management (kill processes)
│       ├── scanner.ts        # Network connection scanner
│       └── watcher.ts        # Real-time port change watcher
├── dist/                    # Compiled output (generated)
├── package.json
├── tsconfig.json
└── README.md

🔧 Tech Stack

• TypeScript — Type-safe JavaScript
• Commander.js — CLI framework
• execa — Process execution
• chalk — Terminal string styling
• systeminformation — System and network info

🌍 Platform Support

| Feature | Windows | macOS / Linux | | ------------ | --------------------------------- | ------------------- | | Port lookup | PowerShell Get-NetTCPConnection | lsof | | Process kill | taskkill | process.kill() | | Network scan | systeminformation | systeminformation |

📄 License

ISC © Anthony Scott