portcheck

A powerful CLI tool for managing ports and processes on your development machine. Find what's using ports, kill processes by port, check service health, and manage port conflicts.

Features

• List Ports: Display all listening ports with process information
• Kill Processes: Kill processes by port number, PID, or name pattern
• Health Checks: Check if ports are open using TCP or HTTP health checks
• Multiple Output Formats: Support for table, JSON, and CSV output
• Cross-platform: Works on macOS, Linux, and Windows

Installation

From Source

git clone https://github.com/yourusername/portcheck.git
cd portcheck
go build -o portcheck
sudo mv portcheck /usr/local/bin/

Using Go Install

go install github.com/yourusername/portcheck@latest

Usage

List All Ports

Display all listening ports on your system:

portcheck list

Output:

PORT   PROTOCOL  STATE   PID    PROCESS        USER     COMMAND
6379   tcp       LISTEN  920    redis-server   maykr    /opt/homebrew/opt/redis/bin/redis-server
8080   tcp       LISTEN  1234   node           maykr    node server.js
3000   tcp       LISTEN  5678   node           maykr    npm start

Find What's Using a Specific Port

portcheck list --port 8080

List Ports by Process Name

portcheck list --name node

List Ports by Process ID

portcheck list --pid 1234

Output Formats

JSON Format

portcheck list --format json

[
  {
    "port": 8080,
    "protocol": "tcp",
    "state": "LISTEN",
    "pid": 1234,
    "process": {
      "pid": 1234,
      "name": "node",
      "command_line": "node server.js",
      "user": "maykr"
    }
  }
]

CSV Format

portcheck list --format csv > ports.csv

Kill Processes

Kill by Port

portcheck kill --port 8080

Kill by PID

portcheck kill --pid 1234

Kill by Process Name

portcheck kill --name node

Force Kill (SIGKILL)

portcheck kill --port 8080 --force

Health Checks

TCP Port Check

portcheck check localhost:8080

Output:

Checking TCP port: localhost:8080
✓ Port localhost:8080 is open (response time: 1.5ms)

HTTP Health Check

portcheck check http://localhost:8080/health

Output:

Checking HTTP endpoint: http://localhost:8080/health
✓ HTTP endpoint is healthy (status: 200, response time: 15ms)

Custom Timeout

portcheck check localhost:8080 --timeout 10s

Command Reference

portcheck list

List all listening ports with process information.

Flags:

• -p, --port <number>: Filter by port number
• -n, --name <pattern>: Filter by process name
• --pid <number>: Filter by process ID
• -f, --format <format>: Output format (table/json/csv)

portcheck kill

Kill processes by port, PID, or name.

Flags:

• -p, --port <number>: Kill process using specific port
• --pid <number>: Kill process by PID
• -n, --name <pattern>: Kill all processes matching name pattern
• -f, --force: Force kill (SIGKILL instead of SIGTERM)

portcheck check

Check if a port is open or service is healthy.

Arguments:

• <host:port>: Check TCP port (e.g., localhost:8080)
• <url>: Check HTTP endpoint (e.g., http://localhost:8080/health)

Flags:

• -t, --timeout <duration>: Connection timeout (default: 5s)

Use Cases

Development Workflow

When you get an "address already in use" error:

# Find what's using the port
portcheck list --port 3000

# Kill the process
portcheck kill --port 3000

Service Management

Check if your services are running:

# Check database
portcheck check localhost:5432

# Check web server
portcheck check http://localhost:8080/health

Process Cleanup

Kill all instances of a development server:

portcheck kill --name node

Export Port Information

Generate a report of all listening ports:

portcheck list --format csv > ports-report.csv

Building from Source

Requirements

• Go 1.21 or higher

Build

go build -o portcheck

Run Tests

go test ./...

Cross-Platform Support

portcheck uses gopsutil for cross-platform process information, providing consistent behavior across:

• macOS (darwin)
• Linux
• Windows

Dependencies

• cobra - CLI framework
• tablewriter - Table output
• color - Terminal colors
• gopsutil - Cross-platform process info

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Author

Built with focus and precision for developers who need reliable port management.