PortCTL - Stop guessing what's running on your machine.

portctl is a fast, cross-platform CLI to inspect ports, understand processes, and recover broken dev environments -- built for real-world development workflows.

See every port, kill rogue processes, manage services, and fix conflicts -- all from the VS Code sidebar.

Features

Sidebar Port Dashboard

Instantly see every listening port on your machine with process name, PID, and service status -- no terminal needed.

Project-Aware Service Management

Detects .portctl.toml in your workspace and shows your services (frontend, backend, database) with live status indicators:

• Running -- green dot
• Stopped -- red dot
• Conflict -- yellow warning

One-Click Actions

Smart Terminal Integration

• Single shared terminal for all actions
• Automatic cleanup when switching between commands
• Interactive TUI support with graceful exit handling

Auto-Install & Update

Extension automatically detects if portctl CLI is installed. If not, it prompts to download the correct binary for your platform (macOS/Linux/Windows, x64/ARM64) from GitHub releases.

Quick Start

1. Install the extension from the VS Code Marketplace
2. Open a project -- the PortCTL icon appears in the activity bar
3. Click the icon to see all listening ports on your machine
4. (Optional) Run portctl init to create a .portctl.toml for service management

Example .portctl.toml

[project]
name = "my-app"

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

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

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

Commands

All commands are available via the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) under the PortCTL category:

• PortCTL: Refresh -- Refresh port and service data
• PortCTL: Start All Services -- Start all services from config
• PortCTL: Stop All Services -- Stop all running services
• PortCTL: Kill Process on Port -- Kill a process by port number
• PortCTL: Restart Service -- Restart a specific service
• PortCTL: View Logs -- Show logs for a service or port
• PortCTL: Fix Port Conflicts -- Auto-resolve port conflicts
• PortCTL: Inspect Port -- Deep inspect a specific port
• PortCTL: Watch Port -- Monitor a port for changes
• PortCTL: Doctor -- Run diagnostic checks
• PortCTL: Preflight Check -- Verify ports before launch
• PortCTL: Switch Profile -- Switch port profile (staging, production)
• PortCTL: Reset to Default Profile -- Restore default port config
• PortCTL: Initialize Project -- Create .portctl.toml in workspace
• PortCTL: Interactive TUI -- Open full terminal interface
• PortCTL: Group by Role -- Group ports by type
• PortCTL: History -- View port usage history
• PortCTL: Scan Dev Ports -- Scan for development servers
• PortCTL: Registry Check -- Check against known services
• PortCTL: CI Check -- Validate for CI/CD
• PortCTL: Update CLI -- Update portctl to latest version

Settings

Requirements

• portctl CLI -- automatically installed via the extension, or install manually:

# macOS (Homebrew)
brew tap abhishekayu/portctl
brew install portctl

# npm (cross-platform)
npm install -g portctl

# From source
cargo install portctl

Supported Platforms

Links

• GitHub Repository
• CLI Documentation
• Report Issues

License

MIT