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
Profile presets — save port combos as named profiles
Port ranges — kill 8000-8010 in one command
Port info — inspect ports without killing (slay info 3000)
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
Shell completions — tab-complete in bash, zsh, and fish
Kill by name — target processes by name with regex, exclude specific processes
Post-kill hooks — auto-run commands after killing (--then "npm start")
Port check — check availability and find next free port for CI scripts
Cross-platform — macOS, Linux, Windows
Zero runtime dependencies

Usage

Kill a port

slay 3000

Kill multiple ports

slay 3000 8080 5432

Kill a port range

slay 8000-8010

Profile presets

# Create a config file
slay init

# Add a profile interactively
slay profile add

# List profiles
slay profile list

# Run a saved profile
slay --profile dev

.slay.json format:

{
  "profiles": {
    "dev": { "ports": [3000, 5173, 5432], "soft": true },
    "clean": { "all": true, "force": true }
  }
}

Supported profile fields: ports, force, yes, soft, verbose, all, watch, dryRun, tree, protocol, name, exclude, thenRun

Tip: CLI flags override profile values. slay --profile dev --force uses the profile's ports but force-kills.

Port info

slay info 3000

Shows PID, command, CPU, memory, and uptime without killing anything.

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

Kill by process name

slay --name node              # Kill all processes named "node"
slay --name "python.*"        # Regex pattern matching
slay --all --exclude nginx    # Kill all except nginx
slay 3000 --exclude postgres  # Kill port 3000 unless it's postgres

Post-kill hook

slay 3000 --then "npm start"           # Auto-restart after kill
slay 3000 -w --then "npm run dev"      # Watch mode + auto-restart

Check port availability

slay check 3000                # Exit 0 if free, exit 1 if occupied
slay check 3000 8080 5432      # Check multiple ports
slay check 3000 --json         # JSON output for scripting
slay check --next 3000         # Find next free port from 3000
slay check --next 3000-4000    # Find next free port in range

Tip: Use in scripts: PORT=$(slay check --next 3000) to get the first available port.

Shell completions

# Bash — add to ~/.bashrc
eval "$(slay completions bash)"

# Zsh — add to ~/.zshrc
eval "$(slay completions zsh)"

# Fish — add to ~/.config/fish/config.fish
slay completions fish | source

Subcommands

Command	Description
`slay init`	Create a `.slay.json` config file in the current directory
`slay profile list`	List all saved profiles
`slay profile add`	Interactively create a new profile
`slay profile rm <name>`	Remove a saved profile
`slay info <port>`	Inspect a port (PID, command, CPU, memory, uptime) without killing
`slay check <port>`	Check if port(s) are free (exit 0 = free, 1 = occupied)
`slay check --next <port>`	Find the next available port starting from `<port>`
`slay completions <shell>`	Output shell completions (bash, zsh, fish)

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
`--profile <name>`	Run a saved profile from `.slay.json`
`--name <pattern>`	Kill processes matching name (supports regex)
`--exclude <pattern>`	Exclude matching processes from kill (repeatable)
`--then <cmd>`	Run command after kill (e.g. `--then "npm start"`)
`-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
findConfig, loadConfig, saveConfig, resolveProfile, mergeProfileOpts — config
getProcessDetail — process detail
checkPort, checkPorts, findNextAvailable, isPortFree — port availability
runHook — post-kill hook execution
matchesPattern, excludeProcesses — process name filtering
findByName — process discovery by name
SlayError — error type
Types: ProcessInfo, KillResult, CliOptions, PlatformAdapter, KillErrorCode, ProcessDetail, ProfileOptions, SlayConfig

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}

// Port check
{"type": "check", "port": 3000, "available": false, "pid": 1234, "command": "node"}

// Next available port
{"type": "next_available", "port": 3001, "range": [3000, 3999]}

// Post-kill hook
{"type": "hook", "command": "npm start", "exitCode": 0, "success": true}

Architecture

src/
  cli.ts              Argument parsing & validation
  config.ts           Config file discovery & profile resolution
  commands/
    init.ts           slay init — create .slay.json
    profile.ts        slay profile list/add/rm
    profile-builder.ts Interactive profile creation TUI
    info.ts           slay info — inspect ports without killing
    check.ts          slay check — port availability & next free port
  completions/
    index.ts          Shell completion dispatcher
    bash.ts           Bash completion script generator
    zsh.ts            Zsh completion script generator
    fish.ts           Fish completion script generator
  core/
    discovery.ts      Port/process discovery
    killer.ts         Process killing logic
    labels.ts         Smart label resolution
    tree.ts           Process tree discovery
    filter.ts         Process name matching & exclusion
    check.ts          Port availability checking
    hook.ts           Post-kill hook execution
  platform/
    index.ts          Platform detection & adapter selection
    unix.ts           macOS/Linux (lsof)
    windows.ts        Windows (netstat/taskkill)
    detail.ts         Process detail (CPU, memory, uptime)
  ui/
    format.ts         Output formatting
    colors.ts         Terminal colors
    animation.ts      Kill animations
    prompt.ts         Confirmation & text input prompts
    interactive.ts    TUI selector
  utils/
    exec.ts           Child process helpers
    errors.ts         Error types

Website

The landing page at slay.fyniti.co.uk features:

9 color themes — Dark, Light, Blood, Synthwave, Matrix, Cyberpunk, Gruvbox, Arctic, Nebula
Per-theme View Transitions — unique animations when switching themes (blood drip, glitch dissolve, VHS wipe, frost crystallize, cosmic swirl, hologram glitch, TV static, and more)
Canvas-based ambient effects — blood rain, matrix falling characters, neon sparks, retro grid, cosmic dust, snowfall, fireflies — all rendered on a full-viewport canvas
Per-theme hero synonyms — rotating tagline changes personality with each theme
10-language i18n support (EN, ZH, HI, ES, AR, FR, BN, PT, RU, JA) with RTL
Interactive terminal demos with animated kill sequences
Live stats from npm and GitHub APIs
Ambient visual effects (gradient mesh, cursor spotlight, scroll progress)
SVG feature icons with per-card hover animations
Responsive design with glassmorphism

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

Name		Name	Last commit message	Last commit date
Latest commit History 151 Commits
.claude		.claude
.github		.github
.husky		.husky
src		src
tests		tests
website		website
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
biome.json		biome.json
jsr.json		jsr.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

slay

Install

Why Slay?

Usage

Kill a port

Kill multiple ports

Kill a port range

Profile presets

Port info

Force kill (no prompt)

Graceful shutdown

Interactive mode

Watch mode

Dry run

Kill process tree

Kill all listeners

JSON output

Pipe to jq

UDP ports

Kill by process name

Post-kill hook

Check port availability

Shell completions

Subcommands

Flags

Interactive Mode

Smart Labels

Programmatic API

JSON Output

Architecture

Website

Cross-Platform Support

Contributing

Contributors

Star History

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages