{"id":48038552,"url":"https://github.com/abhishekayu/portrm","last_synced_at":"2026-04-10T11:01:02.831Z","repository":{"id":349139908,"uuid":"1201185944","full_name":"abhishekayu/portrm","owner":"abhishekayu","description":"Fix broken dev servers instantly. A fast Rust CLI for port conflicts, zombie processes, and dev server recovery.","archived":false,"fork":false,"pushed_at":"2026-04-08T09:17:44.000Z","size":1607,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T09:34:52.197Z","etag":null,"topics":["cargo","cli","command-line","cross-platform","debugger","debugging-tools","developer-tools","devtools","linux","macos","open-source","port-killer","port-management","port-scanner","process-manager","rust","system-programming","terminal","vscode-extension","windows"],"latest_commit_sha":null,"homepage":"https://portrm.dev","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abhishekayu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-04T10:24:35.000Z","updated_at":"2026-04-08T09:17:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/abhishekayu/portrm","commit_stats":null,"previous_names":["abhishekayu/portrm"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/abhishekayu/portrm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhishekayu%2Fportrm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhishekayu%2Fportrm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhishekayu%2Fportrm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhishekayu%2Fportrm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abhishekayu","download_url":"https://codeload.github.com/abhishekayu/portrm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhishekayu%2Fportrm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31639524,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cargo","cli","command-line","cross-platform","debugger","debugging-tools","developer-tools","devtools","linux","macos","open-source","port-killer","port-management","port-scanner","process-manager","rust","system-programming","terminal","vscode-extension","windows"],"created_at":"2026-04-04T14:02:15.790Z","updated_at":"2026-04-10T11:01:02.815Z","avatar_url":"https://github.com/abhishekayu.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"220\" height=\"220\" alt=\"Portrm\" src=\"https://cdn.jsdelivr.net/gh/abhishekayu/portrm@main/assets/logo.png\" /\u003e\n\u003c/p\u003e\n  \u003ch1 align=\"center\"\u003ePortrm\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\u003cstrong\u003eStop guessing what's running on your machine.\u003c/strong\u003e\u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    portrm is a blazing-fast, cross-platform CLI for developers who need to move fast and stay unblocked.\n    Inspect active ports, understand the processes behind them, kill port conflicts, and recover broken dev environments — all from your terminal, in milliseconds.\n\nBuilt for real-world development workflows where every second counts.\u003c/p\u003e\n\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://crates.io/crates/portrm\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/portrm.svg\" alt=\"crates.io\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/portrm\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/portrm.svg\" alt=\"npm\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/portrm/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/portrm.svg\" alt=\"PyPI\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/abhishekayu/portrm/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/abhishekayu/portrm\" alt=\"release\"\u003e\u003c/a\u003e\n    \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"license\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://marketplace.visualstudio.com/items?itemName=abhishekayu.portrm-cli\"\u003e\u003cimg src=\"https://img.shields.io/visual-studio-marketplace/v/abhishekayu.portrm-cli?label=VS%20Code\" alt=\"VS Code Marketplace\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/504fe495-e5d0-4acd-84e6-4f8f578c12dd\" width=\"400\" height=\"400\" alt=\"Portrm Demo\" /\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eDetects the process. Checks if it's safe. Kills it gracefully. Tells you how to restart.\u003c/b\u003e\u003cbr\u003e\n  Try it now: \u003ccode\u003enpx portrm scan\u003c/code\u003e\n\u003c/p\u003e\n\n---\n\n## The Problem Every Developer Hits\n\nYou've seen this before:\n\n```\nError: listen EADDRINUSE: address already in use :::3000\n```\n\nA crashed dev server. A zombie process. Something unknown squatting on your port.\n\nSo you do the ritual:\n\n```bash\nlsof -i :3000           # wall of text\nkill -9 \u003cpid\u003e            # hope it's not PostgreSQL\n# ...was that important?\n# how do I restart this thing?\n```\n\nThis is fragile. It's blind. It tells you nothing about what you just killed.\n\n**portrm replaces this entire workflow with one command.** A single CLI tool for port conflict resolution, process inspection, and dev server recovery.\n\n---\n\n## Instant Port Inspection\n\n```\n$ ptrm 3000\n\n  ⚡ Port 3000 in use\n  → Next.js (PID 81106)\n  → running for 7m 21s\n  → memory 42.9 MB\n  → detected Next.js (95% confidence)\n  → 🛡 safe to kill\n\n  📂 Detected project: Next.js\n  → dev command: npm run dev\n  → default port: 3000\n```\n\nportrm tells you **what** is running, **whether it's safe** to kill, and **how to restart** it.\n\n---\n\n## Port Debugging: Before vs After\n\n| Task                       | Before                                      | After                    |\n| -------------------------- | ------------------------------------------- | ------------------------ |\n| Port 3000 stuck            | `lsof -i :3000 \\| awk ... \\| xargs kill -9` | `ptrm fix 3000`          |\n| \"What's on my ports?\"      | `lsof -iTCP -sTCP:LISTEN` (unreadable)      | `ptrm scan`              |\n| \"Is this safe to kill?\"    | Google the process name                     | portrm tells you         |\n| \"How do I restart?\"        | Dig through package.json                    | portrm shows the command |\n| Zombie processes           | Hunt them one by one                        | `ptrm doctor -y`         |\n| Which port is my frontend? | Check config files                          | `ptrm group`             |\n| Start entire dev stack     | Open 5 terminals, run commands manually     | `ptrm up`                |\n| Stop everything            | Find and kill each process                  | `ptrm down`              |\n| \"Is my port free?\"         | `lsof -i :3000` and parse output            | `ptrm preflight 3000`    |\n| Monitor a flaky server     | Watch logs + manual restart                 | `ptrm watch 3000`        |\n| Duplicate port assignments | Manually diff config files                  | `ptrm registry check`    |\n| Run all checks in CI       | Write custom scripts                        | `ptrm ci`                |\n| Switch dev/staging config  | Edit .env files manually                    | `ptrm use staging`       |\n| Restart a crashed service  | Find port, kill, cd, re-run command         | `ptrm restart frontend`  |\n| \"Are my services running?\" | Check each port manually                    | `ptrm status`            |\n| Stream logs from a port    | Figure out which container or log file      | `ptrm log 3000`          |\n\n---\n\n## Install\n\n\u003e **Native binary. No Node. No runtime dependencies.** ~1.2MB, runs instantly.\n\n### One-line install (recommended)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/abhishekayu/portrm/main/install.sh | sh\n```\n\n### Package managers\n\n| Platform            | Command                                                                                       |\n| ------------------- | --------------------------------------------------------------------------------------------- |\n| **Homebrew**        | `brew install abhishekayu/tap/portrm`                                                         |\n| **Cargo**           | `cargo install portrm`                                                                        |\n| **npm**             | `npm install -g portrm`                                                                       |\n| **pip**             | `pip install portrm`                                                                          |\n| **Scoop** (Windows) | `scoop bucket add portrm https://github.com/abhishekayu/scoop-portrm \u0026\u0026 scoop install portrm` |\n| **Debian/Ubuntu**   | Download `.deb` from [releases](https://github.com/abhishekayu/portrm/releases)               |\n\n### Try instantly (no install)\n\n```bash\nnpx portrm scan\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/abhishekayu/portrm.git\ncd portrm\ncargo install --path .\n```\n\n\u003e **Supports** macOS (Intel + Apple Silicon), Linux (x86_64 + ARM64), and Windows.\n\n---\n\n## Usage Examples\n\n### Scan all listening ports\n\n```\n$ ptrm scan\n\n  ⚡ 5 active ports\n\n  PORT    PROCESS                PID      SERVICE        MEMORY     UPTIME     USER\n  ────────────────────────────────────────────────────────────────────────────────\n  3000    node                   81106    Next.js        42.9 MB    7m 17s     abhishek\n  3898    Code Helper (Plugin)   34290    Python         20.2 MB    3h 12m     abhishek\n  5237    Code Helper (Plugin)   34073    Python         20.1 MB    3h 12m     abhishek\n  5932    Code Helper (Plugin)   61773    Python         57.5 MB    58m 35s    abhishek\n  42050   OneDrive Sync Serv..   36643    Unknown        14.4 MB    3d 1h      abhishek\n```\n\n### Fix port conflicts and auto-restart\n\n```\n$ ptrm fix 3000 --run \"npm run dev\"\n\n  ✔ Killed safely  port 3000 is now free\n  🚀 Restarting: npm run dev\n```\n\nOne command. Port cleared, dev server restarted.\n\n### Diagnose dev environment issues\n\n```\n$ ptrm doctor\n\n  🩺 2 issues found\n\n  1. Idle process Code Helper (PID 34290) at 0.0% CPU [auto-fixable]\n     → Idle Code Helper on port 3898 -- consider killing to free resources\n  2. Idle process Code Helper (PID 34073) at 0.0% CPU [auto-fixable]\n     → Idle Code Helper on port 5237 -- consider killing to free resources\n\n  ⚙ Run ptrm doctor -y to auto-fix 2 issues\n```\n\n### Group ports by service role\n\n```\n$ ptrm group --dev\n\n  ⚡ 4 active ports in 2 groups\n\n  ⚙ Frontend (2)\n  ────────────────────────────────────────────────────────────────────────────\n  3000    node                   81106    Next.js        42.9 MB    7m 21s     abhishek\n  3898    Code Helper (Plugin)   34290    Python         20.2 MB    3h 12m     abhishek\n\n  ⚙ Backend (2)\n  ────────────────────────────────────────────────────────────────────────────\n  5237    Code Helper (Plugin)   34073    Python         20.0 MB    3h 12m     abhishek\n  5932    Code Helper (Plugin)   61773    Python         57.5 MB    58m 39s    abhishek\n```\n\n### Interactive terminal UI\n\n```\n$ ptrm ui\n```\n\nArrow keys to navigate, enter to inspect, `f` to fix. Full interactive TUI for port management, powered by ratatui.\n\n### Define your dev stack with `.ptrm.toml`\n\n```bash\n$ ptrm init\n\n  ✔ Created .ptrm.toml\n  → Detected Next.js project (port 3050)\n  → Port 3050 found in package.json scripts\n```\n\nportrm reads your `package.json` scripts and detects hardcoded ports (`--port 3050`, `-p 8080`, etc.). In a monorepo, it scans subdirectories and generates a multi-service config automatically.\n\nEdit the generated config to declare your services:\n\n```toml\n[project]\nname = \"my-app\"\n\n[services.frontend]\nport = 3000\nrun = \"npm run dev\"\ncwd = \"./frontend\"\npreflight = true\n\n[services.api]\nport = 8080\nrun = \"cargo run\"\ncwd = \"./backend\"\npreflight = true\n\n[services.worker]\nport = 9090\nrun = \"python worker.py\"\nenv = { PYTHON_ENV = \"development\" }\n\n[profiles.staging]\nfrontend = { port = 3100 }\napi = { port = 8180, env = { RUST_LOG = \"info\" } }\n```\n\n### Start your entire dev stack\n\n```\n$ ptrm up\n\n  🚀 Starting 3 services...\n\n  ✔ api started on port 8080\n  ✔ frontend started on port 3050\n  ✔ worker started on port 9090\n\n  ✔ 3/3 services started.\n```\n\nPre-flight checks run automatically. If a port is busy, portrm tells you. Add `-y` to auto-fix conflicts before starting.\n\nportrm tracks spawned PIDs in `.ptrm.pids`. If a framework binds a different port than configured (e.g., Next.js auto-increments when a port is taken), ptrm detects the actual port and reports it:\n\n```\n  ✔ frontend started on port 3001 (configured: 3000)\n      ⚠ port 3000 was busy, update .ptrm.toml to match\n```\n\n### Stop everything\n\n```\n$ ptrm down\n\n  🛑 Stopping 3 services...\n\n  ✔ api stopped (port 8080)\n  ✔ frontend stopped (port 3050)\n  ✔ worker stopped (port 9090)\n\n  ✔ 3/3 services stopped.\n```\n\n`down` uses a 3-tier strategy to find and stop processes: checks the declared port, then the actual port from `.ptrm.pids` (if the process moved), then kills by saved PID directly.\n\n### Pre-flight port check\n\n```\n$ ptrm preflight 3000 8080 5432\n\n  🔍 Pre-flight check for 3 ports...\n\n  ✔ Port 3000 is free\n  ✔ Port 8080 is free\n  ✘ Port 5432 is busy -- postgres (PID 1234, PostgreSQL)\n\n  ⚠ 1 port is already in use. Run ptrm fix \u003cport\u003e to fix.\n```\n\nRun without arguments to check all ports from `.ptrm.toml`.\n\n### Watch a port and auto-restart on crash\n\n```\n$ ptrm watch 3000\n\n  👀 Watching port 3000 (every 2s, Ctrl-C to stop)\n\n  ✔ Port 3000 is up -- Next.js (PID 81106)\n  ✘ Port 3000 went down -- Unknown crash reason (was PID 81106)\n  🚀 Auto-restarting: npm run dev\n  ✔ Port 3000 recovered (PID 82001, Next.js) -- downtime: 3s\n```\n\nIf a `.ptrm.toml` defines a `run` command for the watched port, portrm auto-restarts it when it crashes.\n\n### Validate port assignments\n\n```\n$ ptrm registry check\n\n  🔍 Checking port registry...\n\n  ✔ No port conflicts found across 3 services.\n```\n\nDetects duplicate ports across services and profile overrides in `.ptrm.toml`.\n\n### Run all checks in CI\n\n```\n$ ptrm ci\n\n  ▶ Step 1/4: Validate config... ✔\n  ▶ Step 2/4: Registry check... ✔\n  ▶ Step 3/4: Pre-flight check... ✔\n  ▶ Step 4/4: Doctor... ✔\n\n  ✔ All checks passed.\n```\n\nNon-interactive runner for CI/CD pipelines. Runs config validation, registry check, preflight, and doctor in sequence. Exits 1 on failure. Supports `--json`.\n\n### Switch profiles\n\n```\n$ ptrm use staging\n\n  ✔ Switched to profile: staging\n  → frontend port: 3100\n  → api port: 8180\n```\n\nSwitch between named profiles defined in `.ptrm.toml`. The active profile is persisted to `.ptrm.state` and applied automatically to `up`, `down`, `watch`, and `preflight`.\n\n### Restart a single service\n\n```\n$ ptrm restart frontend\n\n  🔄 Restarting frontend (port 3000)...\n  ✔ Stopped process on port 3000 (PID 81106)\n  ✔ Started frontend on port 3000\n```\n\nRestarts a named service from `.ptrm.toml`. Stops whatever is on the port (local process or Docker container), then re-runs the configured `run` command. Respects the active profile.\n\n### Check service status\n\n```\n$ ptrm status\n\n  📊 test-app status\n\n  SERVICE      PORT    STATUS     PROCESS           PID\n  ──────────────────────────────────────────────────────\n  frontend     3000    🟢 Running  node              81106\n  api          8080    🔴 Stopped\n  worker       9090    🟡 Conflict python3           92001\n```\n\nShows the live status of every service in `.ptrm.toml`. Compares the actual process on each port against the expected service to flag conflicts. Supports `--json`.\n\n### Stream logs from a port\n\n```\n$ ptrm log 3000\n```\n\nStreams live logs from the process on a port. Works with Docker containers (`docker logs -f`) and local processes (detects log files via `lsof`). If the process writes to a TTY, suggests how to redirect output to a file.\n\n---\n\n## CLI Commands Reference\n\n| Command                  | Description                                           | Example                             |\n| ------------------------ | ----------------------------------------------------- | ----------------------------------- |\n| `ptrm scan`              | List all listening ports with service, memory, uptime | `ptrm scan`                         |\n| `ptrm \u003cport\u003e`            | Inspect a single port in detail                       | `ptrm 3000`                         |\n| `ptrm fix \u003cports\u003e`       | Safely kill the process on one or more ports          | `ptrm fix 3000 8080`                |\n| `ptrm fix \u003cports\u003e --run` | Kill and auto-restart a dev server                    | `ptrm fix 3000 --run \"npm run dev\"` |\n| `ptrm fix \u003cports\u003e -y`    | Skip confirmation prompt                              | `ptrm fix 3000 8080 -y`             |\n| `ptrm kill \u003cports\u003e`      | Direct kill with safety confirmation                  | `ptrm kill 3000 8080`               |\n| `ptrm group`             | Ports organized by role (frontend/backend/db/infra)   | `ptrm group --dev`                  |\n| `ptrm doctor`            | Find stale servers, idle processes, conflicts         | `ptrm doctor`                       |\n| `ptrm doctor -y`         | Auto-fix all safe issues                              | `ptrm doctor -y`                    |\n| `ptrm history`           | View past actions with timestamps                     | `ptrm history`                      |\n| `ptrm history --stats`   | Kill stats: success rate, top ports, top processes    | `ptrm history --stats`              |\n| `ptrm project`           | Detect project type, suggest dev commands             | `ptrm project`                      |\n| `ptrm ui`                | Interactive TUI with keyboard navigation              | `ptrm ui`                           |\n| `ptrm init`              | Create a `.ptrm.toml` (auto-detects ports)            | `ptrm init`                         |\n| `ptrm up`                | Start all services from `.ptrm.toml`                  | `ptrm up`                           |\n| `ptrm up -y`             | Start services, auto-fix port conflicts first         | `ptrm up -y`                        |\n| `ptrm down`              | Stop all services from `.ptrm.toml`                   | `ptrm down`                         |\n| `ptrm preflight`         | Check if ports are free before starting               | `ptrm preflight 3000 8080`          |\n| `ptrm watch \u003cport\u003e`      | Monitor a port, alert on crash, auto-restart          | `ptrm watch 3000`                   |\n| `ptrm registry check`    | Validate port assignments for conflicts               | `ptrm registry check`               |\n| `ptrm ci`                | Run all checks non-interactively (CI/CD mode)         | `ptrm ci --json`                    |\n| `ptrm use \u003cprofile\u003e`     | Switch to a named profile from `.ptrm.toml`           | `ptrm use staging`                  |\n| `ptrm restart \u003cservice\u003e` | Restart a named service from `.ptrm.toml`             | `ptrm restart frontend`             |\n| `ptrm status`            | Show live status of all services from config          | `ptrm status`                       |\n| `ptrm log \u003cport\u003e`        | Stream live logs from a port (Docker or local)        | `ptrm log 3000`                     |\n\n\u003e All commands support `--json` for scripting and CI pipelines.\n\n---\n\n## Why portrm Over kill-port, fkill, or lsof\n\n**It's not `kill -9` with extra steps.**\n\nportrm is a process classification engine built for developer productivity:\n\n- **Identifies services** -- Next.js, Vite, Django, Flask, Express, PostgreSQL, Redis, Docker, and 13+ categories with confidence scores\n- **Safety system** -- blocks system-critical processes (PID 1, sshd, launchd), warns about databases (data loss risk), approves dev servers\n- **Graceful shutdown** -- SIGTERM first, waits for clean exit, escalates to SIGKILL only if needed\n- **Project-aware** -- reads package.json, Cargo.toml, pyproject.toml to suggest the right restart command\n- **Docker-aware** -- detects container ports vs host ports\n- **History** -- every action logged to `~/.ptrm/history.json` with timestamps and outcomes\n\n### How portrm works under the hood\n\n1. **Scan** -- queries the OS for all listening ports, resolves PIDs via sysinfo\n2. **Classify** -- identifies the service type (Next.js, PostgreSQL, Docker, etc.)\n3. **Assess** -- safety check: SAFE / WARN / BLOCK\n4. **Strategy** -- picks the right approach: Graceful, Escalating, or Force\n5. **Execute** -- sends signals, waits for exit, verifies the port is free\n6. **Recover** -- detects the project, suggests restart, or auto-restarts with `--run`\n\n### Safety tiers\n\n| Verdict     | Examples                                                    | Behavior                                        |\n| ----------- | ----------------------------------------------------------- | ----------------------------------------------- |\n| **BLOCKED** | PID 0/1, launchd, systemd, sshd, kernel_task                | Refuses to kill                                 |\n| **WARNING** | PostgreSQL, MySQL, Redis, Docker, Nginx                     | Warns about consequences, asks for confirmation |\n| **SAFE**    | Next.js, Vite, Create React App, Django dev, Flask, Node.js | Kills gracefully                                |\n\n---\n\n## Developer Productivity Workflows\n\n### \"Port 3000 is already in use\" after a crash\n\nYour Next.js server crashed. The port is stuck. You just want to get back to coding.\n\n```bash\nptrm fix 3000 -y --run \"npm run dev\"\n```\n\nPort cleared, server restarted. One line.\n\n### Make `npm run dev` crash-proof\n\nAdd ptrm to your scripts so port conflicts resolve themselves:\n\n```json\n{\n  \"scripts\": {\n    \"dev\": \"ptrm fix 3000 -y --run 'next dev'\",\n    \"dev:api\": \"ptrm fix 8080 -y --run 'node server.js'\",\n    \"dev:clean\": \"ptrm doctor -y \u0026\u0026 npm run dev\"\n  }\n}\n```\n\nNow `npm run dev` works every time, even if something is already on port 3000.\n\n### Morning dev environment reset\n\nYou open your laptop. Stale servers from yesterday are hogging ports and memory.\n\n```bash\nptrm doctor -y\n```\n\nFinds zombie processes, idle servers, and cleans them up automatically.\n\n### \"What is using port 8080?\"\n\nSomething is squatting on your API port but you have no idea what.\n\n```bash\nptrm 8080\n```\n\nShows the process name, PID, service type, memory, uptime, project directory, and whether it's safe to kill.\n\n### Full-stack dev with `.ptrm.toml`\n\nFrontend on 3000, API on 8080, worker on 9090. Define them once, manage them forever:\n\n```bash\n# Initialize config\nptrm init\n\n# Start everything (runs preflight checks automatically)\nptrm up\n\n# Stop everything at end of day\nptrm down\n```\n\nNo more opening 5 terminals and running commands manually.\n\n### Monitor a flaky dev server\n\nYour dev server keeps crashing. Let ptrm watch it and auto-restart:\n\n```bash\nptrm watch 3000\n```\n\nIf a `.ptrm.toml` defines a `run` command for port 3000, portrm auto-restarts it when it goes down.\n\n### Pre-flight check before deployment scripts\n\n```bash\n# Check all ports from .ptrm.toml are free\nptrm preflight\n\n# Check specific ports\nptrm preflight 3000 8080 5432\n```\n\n### Shell aliases for daily use\n\n```bash\n# ~/.zshrc or ~/.bashrc\nalias pf='ptrm fix'\nalias pfs='ptrm scan'\nalias pfd='ptrm doctor -y'\nalias pu='ptrm up'\nalias pd='ptrm down'\nalias dev3='ptrm fix 3000 -y --run \"npm run dev\"'\nalias dev8='ptrm fix 8080 -y --run \"node server.js\"'\n```\n\n### Fix multiple ports at once\n\nClearing out a full dev environment before starting fresh:\n\n```bash\n# Fix multiple ports in one command\nptrm fix 3000 8080 5173 -y\n\n# Or with .ptrm.toml\nptrm down \u0026\u0026 ptrm up\n```\n\n### CI / pre-commit: ensure clean ports\n\n```bash\n# Run all checks in one command (exits 1 on failure)\nptrm ci\n\n# Or with JSON output for CI parsing\nptrm ci --json\n```\n\n### Validate port assignments before deploying\n\n```bash\n# Check for duplicate ports across services and profiles\nptrm registry check\n```\n\n### Switch between dev and staging\n\n```bash\n# Define profiles in .ptrm.toml, then switch:\nptrm use staging\nptrm up\n\n# Switch back to default\nptrm use default\nptrm up\n```\n\n### Pipe to scripts with JSON output\n\n```bash\n# Get all listening ports as JSON\nptrm scan --json | jq '.[] | select(.service == \"Next.js\")'\n\n# Count active dev servers\nptrm scan --json | jq '[.[] | select(.service != \"Unknown\")] | length'\n```\n\n---\n\n## Comparison: portrm vs kill-port vs fkill\n\n|                        | kill-port | fkill     | **portrm**                          |\n| ---------------------- | --------- | --------- | ----------------------------------- |\n| Service identification | No        | Name only | Full (service, memory, uptime, CWD) |\n| Safety checks          | No        | No        | Yes (safe / warn / block)           |\n| Graceful shutdown      | No        | No        | Yes (SIGTERM, then escalate)        |\n| Restart hints          | No        | No        | Yes (project-aware)                 |\n| Auto-restart           | No        | No        | Yes (`--run`)                       |\n| Docker awareness       | No        | No        | Yes                                 |\n| Auto-diagnosis         | No        | No        | Yes (`doctor`)                      |\n| Port grouping          | No        | No        | Yes (by role)                       |\n| Action history         | No        | No        | Yes                                 |\n| Interactive TUI        | No        | Yes       | Yes                                 |\n| Project config file    | No        | No        | Yes (`.ptrm.toml`)                  |\n| Dev stack up/down      | No        | No        | Yes (`up` / `down`)                 |\n| Service restart        | No        | No        | Yes (`restart \u003cservice\u003e`)           |\n| Service status         | No        | No        | Yes (`status`)                      |\n| Log streaming          | No        | No        | Yes (`log \u003cport\u003e`)                  |\n| Port monitoring        | No        | No        | Yes (`watch`)                       |\n| Pre-flight checks      | No        | No        | Yes (`preflight`)                   |\n| Crash detection        | No        | No        | Yes (signal, OOM, zombie)           |\n| Port registry          | No        | No        | Yes (conflict detection)            |\n| CI/CD mode             | No        | No        | Yes (`ci` command)                  |\n| Profiles               | No        | No        | Yes (`use` for dev/staging/prod)    |\n| Platform               | Node.js   | Node.js   | Native binary                       |\n| Size                   | ~50MB     | ~50MB     | ~1.2MB                              |\n\n---\n\n## VS Code Extension\n\nManage ports and services directly from the VS Code sidebar -- no terminal needed.\n\n[![Install from VS Code Marketplace](https://img.shields.io/badge/VS%20Code-Install%20Extension-007ACC?logo=visual-studio-code)](https://marketplace.visualstudio.com/items?itemName=abhishekayu.portrm-cli)\n\n**Features:**\n\n- Sidebar dashboard showing all listening ports with process info\n- Project-aware service management (reads `.ptrm.toml`)\n- One-click Start All, Stop All, Fix, Doctor, Preflight, and 15+ actions\n- Switch between dev/staging/production profiles\n- Auto-install and update the ptrm CLI binary\n- Smart single-terminal integration with interactive TUI support\n\n**Install:**\n\n1. Open VS Code\n2. Go to Extensions (`Cmd+Shift+X`)\n3. Search for \"Portrm\"\n4. Click Install\n\nOr install from the command line:\n\n```bash\ncode --install-extension abhishekayu.portrm-cli\n```\n\n[View on Marketplace](https://marketplace.visualstudio.com/items?itemName=abhishekayu.portrm-cli)\n\n---\n\n## Architecture \u0026 Performance\n\n```\nsrc/\n  scanner/      Batch port scanning with sysinfo process resolution\n  classifier/   13+ service classifiers with confidence scoring\n  engine/       Safety checks, strategy selection, graceful kill with retry\n  platform/     macOS (lsof + libc) / Linux (/proc/net/tcp) / Windows (netstat)\n  project/      Filesystem project detection (package.json, Cargo.toml, etc.)\n  docker/       Container awareness via docker ps\n  grouping/     Port role classification (frontend/backend/database/infra)\n  doctor/       Stale servers, idle processes, crowded ports\n  history/      Action log persisted to ~/.ptrm/history.json\n  config/       .ptrm.toml project config loader (monorepo, port detection)\n  watch/        Continuous port monitoring with crash detection\n  stack/        Dev stack orchestration (up/down with PID tracking)\n  preflight/    Pre-flight port availability checks\n  crash/        Crash reason detection (signal, OOM, zombie)\n  restart/      Single-service restart (stop + start from config)\n  status/       Live service status dashboard (running/stopped/conflict)\n  log/          Log streaming for Docker containers and local processes\n  registry/     Port conflict detection across services and profiles\n  ci/           Non-interactive CI/CD runner (config + registry + preflight + doctor)\n  plugin/       Extensible ServiceDetector trait for custom detectors\n  cli/          Clap v4 + colored output + ratatui TUI\n```\n\nBuilt in Rust for speed and reliability. Ships as a single ~1.2MB static binary with zero runtime dependencies. No Node.js, no Python -- just a fast native CLI tool for managing ports and debugging dev environments.\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/abhishekayu/portrm.git\ncd portrm\ncargo build\ncargo test\n```\n\n- Report bugs or request features via [Issues](https://github.com/abhishekayu/portrm/issues)\n- Add new service classifiers\n- Improve platform support\n- Write new doctor diagnostics\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n---\n\n## License\n\n[MIT](LICENSE) -- free for personal and commercial use.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eportrm\u003c/strong\u003e -- an open-source CLI tool for port management, process debugging, and developer environment recovery.\u003cbr\u003e\n  Built for developers who are tired of \u003ccode\u003elsof\u003c/code\u003e + \u003ccode\u003ekill -9\u003c/code\u003e.\u003cbr\u003e\n  Define your dev stack in \u003ccode\u003e.ptrm.toml\u003c/code\u003e, start with \u003ccode\u003eptrm up\u003c/code\u003e, stop with \u003ccode\u003eptrm down\u003c/code\u003e.\u003cbr\u003e\n  Restart a service with \u003ccode\u003eptrm restart frontend\u003c/code\u003e, check status with \u003ccode\u003eptrm status\u003c/code\u003e.\u003cbr\u003e\n  Switch profiles with \u003ccode\u003eptrm use staging\u003c/code\u003e, validate with \u003ccode\u003eptrm ci\u003c/code\u003e.\u003cbr\u003e\n  Works with Next.js, Vite, Django, Flask, Express, Docker, PostgreSQL, Redis, and more.\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabhishekayu%2Fportrm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabhishekayu%2Fportrm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabhishekayu%2Fportrm/lists"}