slay

Kill processes by port. Beautifully.

---

Install

# npm
npx slay-port 3000
npm i -g slay-port

# pnpm
pnpm dlx slay-port 3000
pnpm add -g slay-port

# yarn
yarn dlx slay-port 3000
yarn global add slay-port

# bun
bunx slay-port 3000
bun add -g slay-port

# Homebrew (macOS/Linux)
brew install hammadxcm/slay/slay-port

# Standalone binary (no runtime needed)
# Download from GitHub Releases: https://github.com/hammadxcm/slay/releases

Full docs & interactive demos at slay.fyniti.co.uk

Also available on JSR for Deno and modern TypeScript projects.

Why Slay?

• Interactive TUI with search and multi-select
• Graceful shutdown — SIGTERM first, escalate to SIGKILL
• Watch mode — auto-kill processes that respawn
• Process tree killing — take down children first
• JSON output — pipe to jq for scripting
• Dry run — preview what would be killed
• Smart labels — auto-detects Node.js, Python, Docker, PostgreSQL, and more
• Cross-platform — macOS, Linux, Windows
• Zero runtime dependencies

Usage

Kill a port

slay 3000

Kill multiple ports

slay 3000 8080 5432

Force kill (no prompt)

slay 3000 -f

Graceful shutdown

slay 3000 --soft

Tip: --soft sends SIGTERM first and escalates to SIGKILL only if the process doesn't exit.

Interactive mode

slay -i

Watch mode

slay 3000 -w

Dry run

slay 3000 -n

Kill process tree

slay 3000 -t

Kill all listeners

slay --all -y

JSON output

slay 3000 --json

Pipe to jq

slay 3000 --json | jq '.pid'

UDP ports

slay 53 --udp

Flags

Flag	Description
-f, --force	SIGKILL immediately, skip prompt
-y, --yes	Skip confirmation prompt
--soft	SIGTERM first, escalate to SIGKILL
-v, --verbose	Show signal details, timing, protocol
-n, --dry-run	Preview what would be killed (no kill)
-t, --tree	Kill process tree (children first)
--udp	Target UDP ports instead of TCP
--json	Output NDJSON for scripting
-w, --watch	Keep polling & killing (Ctrl+C to stop)
-i, --interactive	TUI process selector
--all	Kill all listening processes
-h, --help	Show help

Interactive Mode

Launch with slay -i to get a full TUI process selector.

Key	Action
↑ ↓ / j k	Navigate
Space	Toggle selection
a	Toggle all
/	Search
Enter	Confirm kill
q	Quit

Smart Labels

Slay auto-detects process types and known ports:

Recognized commands: Node.js, Python, Ruby, Java, Go, Deno, Bun, PHP, Nginx, Apache, Docker, Electron, VS Code

Known ports:

Port	Label
3000	Dev Server
4200	Angular
5173	Vite
5432	PostgreSQL
3306	MySQL
6379	Redis
8080	HTTP Alt
8888	Jupyter
27017	MongoDB

Programmatic API

import { findByPort, killProcess, platform } from 'slay-port';

const procs = await findByPort(platform, 3000);

for (const proc of procs) {
  const result = await killProcess(platform, proc);
  console.log(`Killed PID ${result.pid} on port ${result.port}`);
}

Exports:

• findByPort, findByPorts, findAllListening — discovery
• killProcess, killAll — killing
• enrichLabel, isSystemPort — labels
• platform, setPlatform — platform adapter
• SlayError — error type
• Types: ProcessInfo, KillResult, CliOptions, PlatformAdapter, KillErrorCode

JSON Output

When using --json, slay emits NDJSON with these event types:

// Process found
{"type": "found", "pid": 1234, "port": 3000, "command": "node"}

// Process killed
{"type": "killed", "pid": 1234, "port": 3000, "signal": "SIGKILL"}

// Kill failed
{"type": "failed", "pid": 1234, "port": 3000, "error": "EPERM"}

// Dry run
{"type": "dry_run", "pid": 1234, "port": 3000, "command": "node"}

// Summary
{"type": "summary", "killed": 1, "failed": 0}

Architecture

src/
  cli.ts              Argument parsing & validation
  core/
    discovery.ts      Port/process discovery
    killer.ts         Process killing logic
    labels.ts         Smart label resolution
  platform/
    index.ts          Platform detection & adapter selection
    unix.ts           macOS/Linux (lsof)
    windows.ts        Windows (netstat/taskkill)
  ui/
    format.ts         Output formatting
    colors.ts         Terminal colors
    animation.ts      Kill animations
    prompt.ts         Confirmation prompts
    interactive.ts    TUI selector
  utils/
    exec.ts           Child process helpers
    errors.ts         Error types

Cross-Platform Support

Platform	Backend
macOS	lsof
Linux	lsof
Windows	netstat + taskkill

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Contributions of all kinds are welcome! Check out the good first issues to get started.

Contributors

Star History

License

MIT — Hammad Khan