rogerchappel/portpatrol

portpatrol

Map local dev ports before your agents trip over mystery servers. 🚦

portpatrol scans a project for ports declared in package scripts, .env, Docker Compose, docs, and config files. It can also inspect live TCP listeners on demand, then emits deterministically ordered Markdown or JSON for handoffs and CI.

Install

PortPatrol is currently distributed from this repository. Install the latest supported source revision with:

git clone https://github.com/rogerchappel/portpatrol.git
cd portpatrol
npm ci
npm run build
npm install -g .
portpatrol --version

When a versioned GitHub release is available, its attached npm tarball can be installed without using the npm registry:

gh release download --repo rogerchappel/portpatrol --pattern 'portpatrol-*.tgz'
npm install -g ./portpatrol-*.tgz
portpatrol --help

Quick start

portpatrol scan . --out docs/PORTS.md
portpatrol suggest --range 3000-3999 --count 3

To try conflict policy handling without a repository checkout, create a small example project with two scripts that declare the same port:

mkdir portpatrol-conflict && cd portpatrol-conflict
printf '%s\n' '{"scripts":{"web":"vite --port 3000","api":"node server.js --port 3000"}}' > package.json
portpatrol scan . --format json --fail-on conflict

The final command reports the duplicate port as a conflict and exits with status 1, which is suitable for enforcing the policy in CI.

Examples

Write a Markdown map:

portpatrol scan . --out docs/PORTS.md

The explicit --out file is excluded from that scan, so regenerating an in-tree Markdown or JSON report does not treat the previous report as project configuration. Other documentation and configuration files are still scanned. Use --out - (or omit --out) to write the report to standard output.

Use strict JSON in CI: