@gks101/port-kill

Lightweight cross-platform port termination for Node.js with programmatic APIs (portKill, portKillSync) and CLI (port-kill), with zero runtime dependencies.

Highlights

• Cross-platform support: Windows, macOS, Linux.
• Multi-port targeting in one command.
• Supports verbose logs, dry-run audits, force/graceful termination, and signal override.
• Safe defaults for dev/test/CI port cleanup workflows.

Compatibility

Area	Support / Requirement	Notes
Node.js	>=16.0.0	Declared in package engines.node.
Windows	cmd.exe, PowerShell	Uses netstat for PID discovery and taskkill for termination.
macOS	Terminal shells (zsh/bash)	Uses lsof with fuser fallback, and kill.
Linux	Terminal shells (bash/sh/zsh)	Uses lsof with fuser fallback, and kill.
Required system tools	lsof, fuser, kill (POSIX); netstat, taskkill (Windows)	Must be available in PATH.

Permission behavior

• Killing processes on protected/privileged ports (for example 80, 443) may require elevated privileges.
• On macOS/Linux this can require sudo.
• On Windows this can require an elevated Administrator shell.
• Without required privileges, commands can fail for those ports and return a non-zero CLI exit code.

Installation

Local (project/test workflows):

npm install --save-dev @gks101/port-kill
yarn add -D @gks101/port-kill
pnpm add -D @gks101/port-kill

Global CLI install (optional):

npm install -g @gks101/port-kill

Run without install:

npx @gks101/port-kill 3000

CLI

port-kill <ports...> [options]

CLI examples

# Single port
port-kill 3000

# Multiple ports in one run
port-kill 3000 8080

# Multiple ports with logs
port-kill 3000 8080 --verbose

# Graceful signal on POSIX
port-kill 3000 8080 --no-force --signal SIGTERM

CLI flags

Flag	Alias	Type	Default	Description
--help	-h	none	n/a	Show help and exit with code 0.
--version	-v	none	n/a	Show version and exit with code 0.
--verbose	-d	none	false	Print verbose execution details.
--dry-run	none	none	false	Discover PIDs without killing them.
--force	none	none	true	Explicitly enforce aggressive termination mode.
--no-force	none	none	false (toggle)	Disable force mode and use graceful termination behavior.
--signal <sig>	-s	string	OS-derived (SIGKILL or SIGTERM)	POSIX-only signal override (ignored on Windows).

Programmatic API

import { portKill, portKillSync } from '@gks101/port-kill';

Function signatures

type PortKillSignal = 'SIGKILL' | 'SIGTERM' | 'SIGINT' | string;

interface PortKillOptions {
  force?: boolean;
  signal?: PortKillSignal;
  verbose?: boolean;
  dryRun?: boolean;
  logger?: (message: string, level?: 'info' | 'warn' | 'error' | 'debug') => void;
}

interface PortKillResult {
  port: number;
  success: boolean;
  pids: number[];
  message: string;
  error?: string;
  timestamp: string;
}

declare function portKill(
  ports: number | number[],
  options?: PortKillOptions
): Promise<PortKillResult[]>;

declare function portKillSync(
  ports: number | number[],
  options?: PortKillOptions
): PortKillResult[];

Programmatic examples (multi-port)

import { portKill, portKillSync } from '@gks101/port-kill';

const asyncResults = await portKill([3000, 8080], {
  verbose: true,
  force: true,
});

const syncResults = portKillSync([3000, 8080], {
  force: false,
  signal: 'SIGTERM',
});

Error and exit behavior

• If a port is already free (no active process found), operation is treated as success.
  • Programmatic: returns success: true for that port.
  • CLI: prints Already free and keeps exit code 0 (unless another targeted port fails).
• CLI returns exit code 1 for parse errors, invalid signals, invalid ports, permission failures, or kill failures.

Chaining note (&&)

If you chain with &&, later commands run only when port-kill exits with 0.

port-kill 3000 8080 && npm run dev

Use this when you want hard-stop behavior. If you want dev server boot to continue even if cleanup fails, use an alternative chain strategy in your shell.

Security notes

• PID lookup and kill are separate OS calls, so a TOCTOU race window can exist on high-churn hosts.
• System binaries are resolved from PATH (lsof, fuser, netstat, kill, taskkill).
• Prefer trusted runtime environments; use elevated privileges only when needed.

License

Apache-2.0