What is pscan?

pscan is a terminal utility that makes it painless to find and kill processes occupying a specific port. Instead of chaining together lsof, grep, and kill commands from memory, you run pscan and pick the process you want to terminate from an interactive list.

It's the tool you reach for when address already in use shows up and you just want to fix it fast.

The Problem It Solves

Port conflicts are a constant friction point in development. The standard workflow involves three commands:

lsof -ti :3000       # find PID
kill -9 <PID>        # kill it

That's fine once, but once you've typed it for the hundredth time — and made a typo in the PID — you start wanting something smarter. pscan wraps that whole flow in a single interactive command.

Core Features

Interactive port scanning

Run pscan and enter the port you want to inspect. pscan queries the OS process table and returns all matching processes with their PID, name, and command line.

pscan 3000
# Found 2 processes on port 3000:
#   [1] node (PID 8421) — next dev
#   [2] python (PID 9033) — http.server
# Kill which one? (1/2/all/none)

Safe by default

pscan always asks for confirmation before sending a signal. You can pass --force to skip the prompt when scripting, but the default is always interactive.

Multi-process support

If multiple processes share a port (e.g. during a failed hot-reload), pscan lists all of them and lets you kill one or all at once.

Signal control

Default kill signal is SIGTERM (graceful). Pass --force to use SIGKILL when a process won't terminate.

pscan 3000 --force   # SIGKILL, no prompt
pscan 8080           # interactive SIGTERM

Installation

npm install -g pscan

Requirements: Node.js ≥ 18, macOS or Linux.

Tech Stack

• TypeScript — strict mode, compiled to a single CLI entry point
• execa — process execution for lsof and kill
• inquirer — interactive terminal prompts
• meow — CLI argument parsing

Design Philosophy

pscan does one thing: find processes by port and give you a clean way to kill them. No config files, no plugins, no background services. It shells out to the OS tools that already exist (lsof, kill) and adds a thin, friendly interface on top.