PORT PILOT — COMMAND SUMMARY
============================

See every local service, understand what launched it, check its health, and stop it safely.

INSTALL
-------

  npm install
  npm run verify
  npm link

MACOS MENU BAR COMPANION
------------------------

  cd macos/PortPilotMenuBar
  swift test
  ./scripts/build-app.sh
  open ".build/release/Port Pilot.app"

The native companion lists and searches services, shows full process/HTTP/Docker details, opens and copies targets, manages aliases, checks ports, sends ready/free/HTTP and lifecycle notifications, and confirms before using the CLI's safe stop action. macOS 13+ is required.

INTERACTIVE DASHBOARD
---------------------

  ports

  Up/Down or j/k       Navigate
  K                    Preview and confirm safe process-tree stop
  o                    Open local service in browser
  e                    Open project directory in an editor
  u / p / c / d        Copy URL / port / command / directory
  f / s / /            Filter / sort / search
  r / q                Refresh / quit

INSPECT AND FILTER
------------------

  ports list
  ports list --range 3000-9999
  ports list --framework astro --project docs
  ports list --all
  ports list --all --user flavio --search worker
  ports list --json
  ports check 4321 --json

AUTOMATION
----------

  ports is-free 4321
  ports wait 4321 --ready
  ports wait 4321 --free
  ports wait 4321 --http 200 --timeout 60 --json
  ports watch --json
  ports watch --all --json

List, watch, and the terminal dashboard show development services by default. Use --all or cycle the dashboard filter to include every listener. `is-free` exits 0 when free and 1 when occupied. Watch mode emits a snapshot followed by started, stopped, and changed events.

SAFE PROCESS ACTIONS
--------------------

  ports kill 4321
  ports kill 4321 --signal INT
  ports kill 4321 --yes --json

Interactive use shows the target context and asks for confirmation. Automation must pass --yes. Descendants are signaled before the listener; TERM escalates to KILL only after a grace period.

ALIASES, OPENING, AND COMPLETIONS
--------------------------------

  ports alias api 8787
  ports check api
  ports open api
  ports alias --remove api

  ports completion bash
  ports completion zsh
  ports completion fish

SYSTEM SUPPORT
--------------

macOS uses lsof and ps. Linux uses ss with lsof fallback and ps. HTTP status, title, and timing appear for likely web ports. Docker mappings appear when Docker is available. No account, key, database, or hosted service is required.

VERIFICATION
------------

  npm run typecheck
  npm test
  npm run build
  npm run verify
  cd macos/PortPilotMenuBar && swift test

See README.md for the complete reference and the package-level SECURITY.md before changing process termination.
