CodewrightConsequence-aware terminal workflows

Kill the process on a port

Medium risk
What do risk levels mean?
Read-only
Inspects state without changing anything.
Low risk
Reversible with a routine follow-up command.
Medium risk
Changes state; undo path documented.
Destructive
Deletes or overwrites; confirmation required.

Frees a TCP port by stopping the process listening on it, after first showing which process holds the port so you do not kill the wrong one.

networkportprocesskill

Parameters

Local TCP port to free.

Commands

Inspect which process is listening before stopping it

lsof -nP -iTCP:<port> -sTCP:LISTEN

Send SIGTERM to the listening process so it can shut down cleanly

lsof -ti tcp:<port> -sTCP:LISTEN | xargs kill

Verification

lsof -nP -iTCP:<port> -sTCP:LISTEN

No rows are returned, meaning the port is free.

Undo

Not undoable

A stopped process cannot be resumed; restart the application manually if it was killed by mistake.

Pitfalls

  • SIGTERM allows graceful shutdown; only escalate to kill -9 if the process ignores it, since forced kills can corrupt in-flight writes.
  • Supervised processes (systemd, Docker, nodemon) may be restarted automatically and re-bind the port immediately.
  • Killing processes owned by another user requires elevated privileges.
  • If nothing is listening on the port, the kill step reports a usage error from kill and changes nothing — that is safe to ignore.
  • The verification command uses macOS/Linux syntax; on Windows use "Get-NetTCPConnection -LocalPort {{port}} -State Listen", which returns nothing when the port is free.

Related