Commands
Show processes listening on common development ports, and stop them safely.
Lists processes listening on TCP ports 3000 3001 4000 4173 5173 5174 8000 8080 8787, or the ports list from your configuration.
broom portsbroom ports --port 3000 # repeatable, or comma-separated: --port 3000,5173broom ports --all # every listening TCP portbroom ports --kill # pick processes to stop, then confirmbroom ports --kill --force # use SIGKILL instead of SIGTERMbroom ports --kill --yes --port 3000broom ports --json broom ports PORT PID PROCESS ADDRESS 3000 4148 node 127.0.0.1 this project 5173 4148 node * this project 5174 98623 Python * Free: 3001, 4000, 4173, 8000, 8080, 8787 3 listeners via lsof. Run with --kill to stop processes.IPv4 and IPv6 sockets of the same process are merged. On macOS and Linux, processes whose working directory is inside the project are marked this project.
| Flag | Description |
|---|---|
-p, --port <ports> | Port(s) to check. Repeatable or comma-separated. |
--all | Show every listening TCP port. |
--kill | Choose processes to stop. Always asks first. |
--force | With --kill: send SIGKILL instead of SIGTERM. |
-y, --yes | With --kill and --port: stop matching processes without prompting. |
| OS | Primary | Fallback | Process details |
|---|---|---|---|
| macOS | lsof -F | – | ps |
| Linux | lsof -F | ss -tlnp | ps, /proc/<pid>/cwd |
| Windows | Get-NetTCPConnection | netstat -ano (locale-independent) | Win32_Process / tasklist |
All commands run with argument arrays and shell: false. Before killing, Broom re-scans the port and checks the process start time, so a process that exited, stopped listening, or whose PID was reused is not signalled. Broom refuses to signal PID 0/1, Windows System (4), itself and its parent shell. --kill --yes requires explicit --port values.
Without elevated privileges, macOS and Linux may hide other users' processes; Broom warns when a PID is unknown. Windows cannot report a process's working directory.
Found a problem in these docs? Open an issue on GitHub.