.portkill: A minimalist CLI to find and free stuck TCP ports without the lsof xargs kill dance
.portkill is a compact CLI that finds and frees occupied TCP ports, previews actions with –dry-run, and provides a loopback GUI for local development.
A practical tool for an annoyingly common problem
Every developer who runs local servers has hit the same wall: EADDRINUSE, an unexpected PID, and the familiar terminal scramble of lsof, xargs and kill. .portkill is a small, Node-based utility that surfaces the listener, shows a safe preview, and then stops only the processes you intend—either from the terminal or through a tiny loopback web UI. It packages a familiar workflow into a single binary (installed as portkill) so you can list listeners, inspect owners by name and PID, preview signals with –dry-run, and dispatch graceful or forced terminations with clear defaults that reduce the risk of accidentally killing unrelated processes.
What .portkill does and why it matters
The core value proposition of .portkill is convenience plus safety. On macOS and Linux, developers traditionally combine tools like lsof and fuser, then pipe results into kill -9 or manually hunt PIDs. That approach is powerful but error-prone: it encourages guesswork and can lead to unintentionally terminating critical processes. .portkill replaces those multi-command pipelines with a single command that:
- Enumerates TCP listeners and reports process name and PID for each occupied port.
- Lets you preview the exact targets with –dry-run before any signal is sent.
- Sends signals using a controlled CLI flow, with prompts unless you pass –force.
- Offers an optional local web UI (bound to 127.0.0.1 / ::1) for browser-based confirmation and a calmer decision surface.
For fast-moving development environments—microservices, hot-reloading apps, live-reload front-ends—the ability to quickly identify what is bound to 3000 or 8080 and release it without guessing PIDs is a time-saver and a safety improvement.
How .portkill works under the hood
.portkill is implemented for Node.js runtimes (Node 18 or newer). On supported platforms it leverages the same underlying OS utilities you would use manually: lsof is the primary source of truth for identifying TCP listeners; on some Linux distributions fuser can act as a fallback. The tool parses those outputs into a concise table mapping ports to process names and PIDs, then exposes an interface for sending signals.
The default behavior is conservative: SIGTERM is used unless you override it with –signal. Before sending anything, .portkill can run in a preview-only mode (–dry-run) that prints the exact targets and actions that would take place. If you prefer a graphical confirmation step, –gui starts a minimal HTTP server on loopback and prints a local URL—there is no Electron bundle, no cross-network exposure, and the UI logic mirrors the CLI commands.
The range handling supports port ranges (for example 9000-9002) with a sensible cap: up to 4,096 ports per range token to prevent accidental broad sweeps. When a user asks for ports explicitly (e.g., portkill 3000 8080), .portkill only examines and acts on those ports, rather than mass-killing listeners.
Install and quick start for local development
.portkill is published as an npm package under the scoped name @burakboduroglu/portkill and installs as the CLI binary portkill. There are two common installation approaches:
- Global install: npm i -g @burakboduroglu/portkill will place portkill on your PATH.
- One-off invocation: npx @burakboduroglu/portkill lets you run the tool without a global install.
From there, basic workflows look like:
- List listeners: portkill –list
- Preview actions for ports 3000 and 8080: portkill 3000 8080 –dry-run
- Release listeners on ports 3000 and 8080: portkill 3000 8080
- Open the minimal UI on loopback: portkill –gui
When the GUI is running it prints a loopback-only URL; use Ctrl+C in the terminal to stop the server. The local UI uses the same logic as the CLI, so you get parity between the two interfaces.
If you prefer building from source, the repository includes a conventional Node.js development flow (npm install, npm run build, optional npm link to add portkill to PATH). The project relies on standard developer tooling—tests, linting, and optional coverage scripts are included in the repository to support contributors.
CLI flags and safety features
.portkill exposes a set of focused CLI flags designed to make common tasks explicit and avoid mistakes:
- –list (-l): scan and list all TCP listeners.
- –dry-run (-n): show what would be targeted; send no signals.
- –force (-f): skip terminal confirmation prompts.
- –signal (-s): choose which signal to send (default SIGTERM).
- –gui: start the loopback web UI.
- –verbose (-v): emit more diagnostic detail to stderr.
Defaulting to SIGTERM is an intentional safety choice: it gives well-behaved processes a chance to clean up rather than terminating them abruptly with SIGKILL. The confirmation prompt and dry-run mode together provide a two-step safety net—see what will be killed, then explicitly proceed—helpful in multi-service environments where multiple processes may be listening on adjacent ports.
The local web UI: a calm alternative to electron apps
One of .portkill’s differentiators is a browser-based UI that runs only on loopback (127.0.0.1 and ::1). The design rationale is simple: developers want a visual confirmation and easier selection of targets, but they do not want another Electron background app or global server.
The GUI is intentionally lightweight: it is an in-process HTTP server that offers the same insights as the CLI (process name, PID, port, address families). Because it is bound to loopback, the UI cannot be accessed over a network by default, reducing attack surface. The UI mirrors CLI actions, including preview and confirmation workflows, so switching between terminal and browser feels consistent.
For teams that prefer a graphical approach during local debugging—pair programming, onboarding, or demos—the loopback UI provides a low-friction alternative that preserves the precise control developers need.
Compatibility, requirements, and platform behavior
.portkill targets environments where lsof or similar utilities are available. Key requirements:
- Node.js 18 or newer is required to run the binary.
- Supported operating systems: macOS and Linux.
- lsof is used for process discovery; on certain Linux setups fuser may be used as a fallback where applicable.
Because macOS and Linux differ in how they represent sockets and PIDs, .portkill adapts its discovery layer to provide consistent output. Windows is not listed among official supported platforms because the underlying process-discovery utilities and socket semantics differ; Windows users will need equivalent tooling or a different solution that integrates with netstat and Windows process management APIs.
When you operate .portkill in automated scripts or CI environments, be mindful of its exit codes and the potential for needing elevated privileges to send signals to processes owned by other users. The project provides a CLI reference in its documentation (CLI reference and exit code definitions are available in repo docs) that explains behaviour in scripted contexts.
Developer workflows and practical use cases
.portkill is engineered for the everyday friction of local development. Typical scenarios include:
- Hot-reloading servers that crash and leave sockets in a TIME_WAIT or zombie state.
- Containerized local stacks where a prior instance failed to shut down cleanly and left ports bound.
- Switching branches or projects that each expect to bind the same development port (3000, 8080, etc.).
- Running multiple dev servers in parallel during microservice development and needing to free a port quickly.
For each case, .portkill helps maintain momentum by replacing multi-step shell pipelines with an explicit, previewable command. Integrations into developer-friendly shell aliases, local dev scripts, or task runners are trivial: portkill 3000 can be a pre-start step in a dev script that checks and clears a port if necessary.
The package’s distribution model (npm-only) aligns with typical JavaScript developer workflows, and the small footprint—Node only, no Electron—keeps overhead low. Mentions of a "CLI reference" and "npm package page" in documentation make it easy for teams to add .portkill to dev-machine setup instructions or internal tooling repositories.
Security and operational considerations
While .portkill is intentionally conservative, there are still operational considerations to keep in mind:
- Permissions: Sending signals to processes owned by other users generally requires elevated privileges. Running portkill as root or via sudo will increase its ability to act across users but also amplifies risk.
- Scope: Port ranges and bulk operations can be powerful. The tool enforces a per-range cap (4,096 ports per range token) to limit accidental wide-ranging effects, but users should still avoid issuing wide ranges on multi-tenant developer machines.
- Loopback-only GUI: The GUI is bound to 127.0.0.1 / ::1, not a public network interface. This drastically reduces exposure, but developers should avoid manual configuration changes that would bind the UI to non-loopback interfaces.
- Reproducibility in CI: Using portkill in CI should be considered carefully. In continuous integration environments, deterministic provisioning of ports and containers is preferable to terminating processes dynamically. If portkill is used to prepare ephemeral test runners, document exact expectations and exit codes to avoid flakiness.
- Auditing and logging: .portkill provides verbose output for diagnostic purposes. Teams that need audit trails should wrap portkill in scripts that log actions to internal logging systems or datastore entries when used in shared environments.
Comparisons and ecosystem context
.portkill sits among a number of developer utilities intended to simplify local operations. Compared with manual lsof + xargs workflows, .portkill combines discovery and action into a single command and adds interactive safeguards. Compared with heavier GUI tools—often Electron-based—.portkill favors minimalism and no extra background processes. From an ecosystem standpoint, .portkill complements developer tooling such as:
- Local orchestration tools and container runtimes (Docker, Podman) where ports are frequently claimed and released.
- Live-reload dev servers and frameworks that rely on specific ports (Next.js, Vite, Create React App).
- Developer productivity tooling that manages environment variables and processes (dotenv utilities, task runners).
It also plays well alongside security and automation tooling: process discovery and signal semantics are standard OS behavior, and .portkill simply wraps those into a more approachable interface.
Contributing, code quality and maintenance notes
The source repository includes standard development scripts: npm run build, npm test, npm run lint, and coverage-oriented test scripts. Terminal coloring uses the chalk library; disabling colors is possible via NO_COLOR=1, adhering to the broader no-color convention used by many command-line utilities.
The project is released under the MIT license, and distribution is handled through npm (the package readme is included in the published package for discoverability). For contributors, the repository contains docs and a product spec, making it straightforward to extend discovery behavior, add platform adapters, or improve the GUI.
Broader implications for developer tooling and local environments
Tools like .portkill point to a larger trend in developer tooling: the consolidation of small, often-repeated command sequences into single-purpose utilities with safe defaults and discoverability. There are several implications for teams and tooling ecosystems:
- Reduced cognitive load: Developers spend less time remembering shell incantations and more time on feature work. That matters in onboarding and when switching contexts between projects.
- Safer defaults: Defaults like SIGTERM and the presence of a dry-run encourage conservative, reversible actions. Over time, toolchains that favor safety reduce accidental outages in shared dev machines or local testbeds.
- Minimal UIs: The decision to deliver a loopback web UI rather than a full Electron app reflects a growing preference for lightweight, composable tools that do one thing well and integrate into existing workflows.
- Niche tooling maturity: As small tools become stable and discoverable via package registries, they can be composed into larger developer automation stacks—pre-commit hooks, dev-setup scripts, or orchestration recipes.
For platform vendors and tooling maintainers, this pattern also raises expectations: a small, reliable utility should have clear docs, predictable behavior, and a straightforward path for integration. Projects that meet these expectations are more likely to be adopted across organizations and to be included in internal developer onboarding materials or standard toolchains.
Who should consider using .portkill
.portkill is aimed at developers, system administrators responsible for local developer environments, and engineers who frequently manage multiple local services. It is especially useful for:
- Front-end and full-stack developers who repeatedly bind common ports while switching projects.
- Backend developers running local microservices that might leave sockets in inconsistent states.
- Engineers maintaining developer workstations or team dev images who want a simple, auditable way to free ports.
- Contributors to open-source projects where a lightweight, documented command prevents noisy setup issues in issue queues.
It is less relevant as a solution for production servers; process management at scale generally falls to orchestration systems and service managers (systemd, Kubernetes), where different semantics and control planes are in place.
.portkill’s command set and behavior work well as part of local development tooling documentation. Phrases like "CLI reference" or "npm package page" point users to the upstream docs for detailed command and exit-code information, while "GitHub" indicates the source for contributions and the product spec.
.portkill in automation and scripting contexts
Because .portkill exposes a straightforward set of flags and predictable exit codes (documented in the repository), it is amenable to scripted usage. Common patterns include:
- Pre-start checks in npm scripts that ensure a port is free before starting a dev server.
- Small CI runners that need to reclaim ephemeral ports between test runs on shared agents.
- Local dev orchestration scripts that prepare the host environment before launching multiple services.
When integrating .portkill into scripts, prefer –dry-run for diagnostics during development and test the behavior under different privilege levels (standard user vs. sudo) to ensure consistent outcomes.
A forward look at minimal developer utilities
.portkill demonstrates that small, focused utilities with safe defaults and clean UX can make a disproportionate difference in day-to-day developer productivity. Expect to see more tools that wrap standard OS primitives into tidy CLIs and tiny loopback UIs—solutions that erase friction without introducing new dependencies or background services. Continued enhancements could include broader platform support, richer integration hooks for editor extensions or IDE tool windows, and configurable policies for teams that want stricter governance around process termination. These kinds of lightweight utilities will continue to shape developer machine ergonomics and the way teams document and automate local workflows.
