How to use Port Pilot
Port Pilot
Find local development servers, inspect their health, use port aliases and stop the correct process.
Bought Port Pilot? Sign in with the email you bought it with to download the latest version or ask me a question.
On this page
Port Pilot shows which local services are listening, what started them and whether their HTTP endpoint responds. You can use a terminal dashboard, individual ports commands or the optional Mac menu bar app.
Install
After purchase, download the runtime ZIP from your purchase page and unzip it.
You need Node.js 20 or later and npm. Port scanning works on macOS with lsof, and Linux with ss or lsof. From the unzipped folder:
npm install --global --prefix ~/.local ./port-pilot-*.tgz
Add ~/.local/bin to your PATH if your shell cannot find ports. Run it without arguments to open the terminal dashboard:
ports
Find a server
Suppose an Astro project says port 4321 is occupied. Inspect that port before stopping anything:
ports check 4321
The result can include its PID, project directory, command, parent process and HTTP status. Docker details appear when available. The walkthrough is Find what’s using a port on macOS, and which project it belongs to.
List other development servers:
ports list
ports list --range 3000-9999
ports list --framework astro
The default list includes listeners with development evidence, such as a project, framework, runtime or Docker mapping. Add --all to include system and unknown listeners:
ports list --all
Use the dashboard
The dashboard refreshes automatically. These keys work on the selected row:
| Key | Action |
|---|---|
Up/Down or j/k | Select a service |
/ | Search process metadata |
f | Cycle service filters |
s | Cycle sorting |
o | Open its local URL |
e | Open the project directory |
u, p, c, d | Copy URL, port, command or directory |
K | Preview stopping the process tree |
r | Refresh |
q | Quit |
Stop the correct process
After checking the project and command, ask Port Pilot to stop it:
ports kill 4321
Review the preview before confirming. The default is SIGTERM, with descendants signaled before the owner. Processes remaining after the grace period can receive SIGKILL.
Stopping a process can interrupt unsaved work or an active request. Use the interactive form while learning the tool. Automation can skip confirmation with --yes, but should inspect the service first.
Name a port
Give a local API a short alias:
ports alias api 8787
ports check api
ports open api
List aliases with ports alias. Remove one with ports alias --remove api. Aliases are kept in your user configuration outside the project.
Use ports in scripts
is-free exits with status 0 for a free port and 1 for an occupied one:
ports is-free 4321
Wait for a server to return HTTP 200, or wait until its listener disappears:
ports wait 4321 --http 200 --timeout 60
ports wait 4321 --free
Use ports list --json for structured records. ports watch --json emits a snapshot followed by service lifecycle events.
Optional Mac companion
The ZIP includes a notarized Port Pilot.app. Move it to Applications and open it after installing the CLI.
The menu bar app uses the same CLI for scanning and stopping. Its Show all control reveals listeners excluded from the development view.
If a service is missing, try Show all or --all first. Reopen your purchase page to download and install future versions.
More examples
- See which Docker container published a local port
- Find what's using a port on macOS, and which project it belongs to
- Fix “EADDRINUSE: address already in use” on a local port
- Wait until a local server is ready before running tests
Port Pilot is $20, a one-time purchase.