Examples

Real-world scenarios and copy-paste commands for common workflows.

Fix a Crashed Dev Server

Your Next.js app crashed and port 3000 is stuck:

$ npm run dev
Error: listen EADDRINUSE: address already in use :::3000

$ ptrm fix 3000 --run "npm run dev"

  Port 3000 in use
  Node.js (PID 42891) - Next.js dev server
  SAFE - dev server
  Killed PID 42891 (SIGTERM)
  Port 3000 is now free
  Starting: npm run dev

Clean Up Before Starting Work

Before you start your dev session, clean up zombie processes:

$ ptrm doctor -y

  Scanning for issues...
  Found 2 zombie processes
  Found 1 idle server (port 8080, running 3 days)
  Cleaned up 3 processes
  All ports healthy

Full Stack Project Setup

Set up a project with frontend, API, and database:

# 1. Initialize portrm config
$ ptrm init

# 2. Edit .ptrm.toml
[project]
name = "my-saas-app"

[services.frontend]
port = 3000
run  = "npm run dev"
cwd  = "./frontend"

[services.api]
port = 8080
run  = "cargo run"
cwd  = "./api"

[services.db]
port = 5432
run  = "pg_ctl start"

[services.redis]
port = 6379
run  = "redis-server"

[profiles.staging]
frontend = { port = 3100 }
api      = { port = 8180 }

# 3. Start everything
$ ptrm up -y

  Preflight: checking ports 3000, 8080, 5432, 6379
  All ports free
  Starting frontend... OK (port 3000)
  Starting api... OK (port 8080)
  Starting db... OK (port 5432)
  Starting redis... OK (port 6379)
  All 4 services running

CI/CD Pipeline

Add portrm to your CI pipeline to catch port conflicts:

# GitHub Actions example
- name: Check ports
  run: |
    npm install -g portrm
    ptrm ci --json

# The ci command runs:
# 1. Config validation
# 2. Registry check
# 3. Preflight (are ports free?)
# 4. Doctor (any zombie processes?)
# Exits with code 1 on failure

Docker Workflow

When Docker containers conflict with local services:

# Find what is using the port Docker needs
$ ptrm 5432

  Port 5432
  Process:  postgres (PID 291)
  Service:  PostgreSQL
  Safety:   DATABASE - data loss risk
  Use --force to override

# If you need to free it for Docker
$ ptrm fix 5432 --force -y

# Or check all ports your docker-compose needs
$ ptrm preflight 3000 5432 6379 8080

Scripting & Automation

Use JSON output for scripts:

# Get port info as JSON
$ ptrm 3000 --json
{
  "port": 3000,
  "pid": 42891,
  "process": "node",
  "service": "Next.js",
  "safety": "safe",
  "memory_mb": 14.2,
  "uptime_seconds": 3600
}

# Use in a shell script
if ptrm preflight 3000 8080 2>/dev/null; then
  echo "Ports are free, starting services..."
  npm run dev &
else
  echo "Port conflict detected, fixing..."
  ptrm fix 3000 8080 -y
  npm run dev &
fi

Switch Between Dev Environments

# Define profiles in .ptrm.toml
[profiles.staging]
frontend = { port = 3100, env = { API_URL = "https://staging-api.example.com" } }
api      = { port = 8180 }

# Switch profiles
$ ptrm down
$ ptrm use staging
$ ptrm up

Monitor a Flaky Server

# Watch port 3000 and auto-restart on crash
$ ptrm watch 3000

  Watching port 3000...
  [14:30:12] Server running (PID 42891)
  [14:45:33] Server crashed! Restarting...
  [14:45:34] Server running (PID 42920)

More questions? Check the command reference or open an issue on GitHub.