Port Pilot

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

Connect your GitHub account in Polar after purchase and accept the invitation. Clone the customer repository with your authorized GitHub account.

You need Node.js 20 or later and npm. Port scanning works on macOS with lsof, and Linux with ss or lsof. From the repository root:

npm install
npm run verify
npm link

The executable is called 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.

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 purchase includes the companion’s source. Build it on macOS 13 or later with Xcode/Swift, after installing the CLI:

cd macos/PortPilotMenuBar
./scripts/build-app.sh

Open .build/release/Port Pilot.app. It 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. Download source updates manually from the private repository, rebuild and reinstall with the same steps.