{
"name": "portctl",
"tagline": "Fix broken dev servers instantly.",
"description": "A fast, cross-platform CLI tool that detects, explains, and fixes port conflicts, zombie processes, and broken dev servers.",
"short_description": "Fix port conflicts, debug processes, and recover dev environments instantly.",
"language": "Rust",
"license": "MIT",
"platforms": ["macOS", "Linux", "Windows"],
"architectures": ["x86_64", "arm64"],
"binary_size": "~980KB",
"runtime_dependencies": [],
"repository": "https://github.com/abhishekayu/portctl",
"homepage": "https://github.com/abhishekayu/portctl",
"packages": {
"crates_io": "https://crates.io/crates/portctl",
"npm": "https://www.npmjs.com/package/portctl",
"homebrew": "brew tap abhishekayu/tap && brew install portctl"
},
"install": {
"homebrew": "brew tap abhishekayu/tap && brew install portctl",
"cargo": "cargo install portctl",
"npm_global": "npm install -g portctl",
"npx": "npx portctl scan",
"shell": "curl -fsSL https://raw.githubusercontent.com/abhishekayu/portctl/main/install.sh | sh"
},
"commands": [
{
"name": "scan",
"syntax": "portctl scan",
"description": "List all listening ports with process name, PID, service type, memory, uptime, and user.",
"flags": ["--json"]
},
{
"name": "info",
"syntax": "portctl <port>",
"description": "Inspect a single port with detailed process and service information.",
"example": "portctl 3000"
},
{
"name": "fix",
"syntax": "portctl fix <port>",
"description": "Identify process on port, run safety checks, gracefully kill, suggest restart.",
"flags": ["-y", "--run \"cmd\"", "--json"],
"examples": [
"portctl fix 3000",
"portctl fix 3000 -y",
"portctl fix 3000 --run \"npm run dev\""
]
},
{
"name": "kill",
"syntax": "portctl kill <port>",
"description": "Direct kill with safety confirmation.",
"example": "portctl kill 8080"
},
{
"name": "group",
"syntax": "portctl group",
"description": "Group listening ports by role: frontend, backend, database, infrastructure.",
"flags": ["--dev", "--json"],
"example": "portctl group --dev"
},
{
"name": "doctor",
"syntax": "portctl doctor",
"description": "Auto-diagnose dev environment: stale servers, idle processes, port conflicts.",
"flags": ["-y", "--json"],
"examples": ["portctl doctor", "portctl doctor -y"]
},
{
"name": "history",
"syntax": "portctl history",
"description": "View past portctl actions with timestamps and outcomes.",
"flags": ["--stats", "--json"],
"examples": ["portctl history", "portctl history --stats"]
},
{
"name": "project",
"syntax": "portctl project",
"description": "Detect project type and suggest dev commands.",
"example": "portctl project"
},
{
"name": "ui",
"syntax": "portctl ui",
"description": "Interactive terminal UI with keyboard navigation for port management.",
"example": "portctl ui"
}
],
"safety_system": {
"tiers": [
{
"level": "BLOCKED",
"description": "System-critical processes. portctl refuses to kill.",
"examples": ["PID 0", "PID 1", "launchd", "systemd", "sshd", "kernel_task", "WindowServer"]
},
{
"level": "WARNING",
"description": "Databases and infrastructure. Warns about data loss risk.",
"examples": ["PostgreSQL", "MySQL", "Redis", "MongoDB", "Docker", "Nginx"]
},
{
"level": "SAFE",
"description": "Dev servers. Kills gracefully.",
"examples": ["Next.js", "Vite", "Create React App", "Django", "Flask", "Express"]
}
]
},
"supported_services": [
"Next.js", "Vite", "Create React App", "Webpack Dev Server",
"Django", "Flask", "Express",
"PostgreSQL", "MySQL", "Redis", "MongoDB",
"Docker", "Nginx",
"Node.js", "Python"
],
"kill_strategies": [
{
"name": "Graceful",
"method": "SIGTERM + wait",
"use_case": "Dev servers"
},
{
"name": "Escalating",
"method": "SIGTERM, wait, then SIGKILL",
"use_case": "Stubborn processes"
},
{
"name": "Force",
"method": "SIGKILL",
"use_case": "Explicit user request"
}
],
"project_detection": {
"package.json": "Node.js / Next.js / Vite",
"Cargo.toml": "Rust",
"pyproject.toml": "Python",
"requirements.txt": "Python",
"docker-compose.yml": "Docker",
"Gemfile": "Ruby"
},
"keywords": [
"port", "kill-port", "port-conflict", "EADDRINUSE", "address-already-in-use",
"developer-tools", "CLI", "devserver", "process", "debug",
"zombie-process", "port-scanner", "dev-environment", "productivity",
"lsof-alternative", "fkill-alternative", "kill-port-alternative",
"graceful-shutdown", "process-manager", "Rust-CLI", "TUI"
],
"comparison": {
"vs_kill_port": "portctl adds safety checks, service classification, graceful shutdown, restart hints, doctor, TUI. Native binary vs Node.js.",
"vs_fkill": "portctl adds safety assessment, graceful shutdown, project-aware restart, auto-diagnosis. Native binary vs Node.js.",
"vs_lsof_kill": "portctl is a single command that identifies, assesses safety, kills gracefully, and suggests restart. No manual PID parsing."
}
}