port-conflict-resolver

A cross-platform CLI utility that helps developers quickly identify and resolve port conflicts. Given a port number, it detects which process is using it and offers a single command to terminate that process across Linux, macOS, and Windows.

Features

• Process Detection: Identify which process is using a specific port
• Process Termination: Kill processes gracefully or forcefully
• Port Listing: View all active ports and their processes
• Interactive Mode: Select and kill multiple ports interactively
• Configuration: Auto-kill ports, ignore system ports, custom grace periods
• Auto-Updates: Check for latest releases from GitHub
• Cross-Platform: Works on Linux, macOS, and Windows

Installation

From Source

git clone https://github.com/am-miracle/port-conflict-resolver.git
cd port-conflict-resolver
cargo build --release

The binary will be at target/release/port-conflict-resolver.

Add to PATH (Optional)

# Linux/macOS
sudo cp target/release/port-conflict-resolver /usr/local/bin/pcr

# Or add to PATH in your shell profile
export PATH="$PATH:/path/to/port-conflict-resolver/target/release"

Usage

Check a Port

pcr check 8080

Output:

✓ Port 8080 is in use
  PID: 12345
  Process: node
  Command: node server.js

Kill a Process on a Port

# Graceful kill (SIGTERM)
pcr kill 8080

# Force kill (SIGKILL)
pcr kill 8080 --force

List All Active Ports

pcr list

Output:

PORT    PID     PROCESS         COMMAND
3000    1234    node           node server.js
8080    5678    python3        python3 -m http.server

Get Detailed Port Info

pcr info 8080

Interactive Mode

pcr interactive

Commands in interactive mode:

• 1-9: Toggle port selection
• a or all: Select all ports
• n or none: Deselect all
• k or kill: Kill selected ports
• q or quit: Exit

Check for Updates

pcr update

Show Version

pcr version

Configuration

Config file location: ~/.config/pcr/config.toml

Example configuration:

# Ports that will be killed without confirmation
auto_kill_ports = [3000, 8080]

# Ports to ignore in listings (system ports)
ignored_ports = [22, 80, 443]

# Wait time before force kill (milliseconds)
grace_period_ms = 2000

Testing

Quick Test

# Run all tests (unit + integration)
cargo test

Test Types

• Unit Tests: 62 tests covering all modules
• Integration Tests: 16 tests covering CLI operations

Run Specific Tests

# Unit tests only
cargo test --bin port-conflict-resolver

# Integration tests only
cargo test --test test

# Specific test
cargo test test_cli_version

# With output
cargo test -- --nocapture

Development

Project Structure

port-conflict-resolver/
├── src/
│   ├── main.rs              # Entry point & command handlers
│   ├── cli.rs               # CLI argument definitions
│   ├── finder.rs            # Cross-platform process detection
│   ├── killer.rs            # Process termination logic
│   ├── utils.rs             # Output formatting & errors
│   └── enhancements/
│       ├── config.rs        # Configuration management
│       ├── interactive.rs   # Interactive TUI mode
│       └── updater.rs       # Version checking
├── tests/
│   └── test.rs              # Integration tests
├── Cargo.toml
├── README.md
└── TESTING.md               # Testing guide

Run in Development

cargo run -- check 8080
cargo run -- list
cargo run -- --help

Build for Release

cargo build --release

Platform Support

Linux

• Uses lsof and ss for process detection
• Uses kill with SIGTERM/SIGKILL

macOS

• Uses lsof for process detection
• Uses kill with SIGTERM/SIGKILL

Windows

• Uses netstat for process detection
• Uses taskkill with /T (graceful) or /F (force)

Requirements

• Rust 1.70+ (edition 2024)
• Platform-specific tools:
  • Linux: lsof, ss, kill
  • macOS: lsof, kill (pre-installed)
  • Windows: netstat, taskkill (pre-installed)

Dependencies

• clap - CLI argument parsing
• sysinfo - System & process information
• colored - Terminal colors
• anyhow - Error handling
• tokio - Async runtime
• serde + toml - Configuration serialization
• indicatif - Progress indicators
• reqwest - HTTP client for updates

See Cargo.toml for complete dependency list.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Run tests: cargo test
5. Commit: git commit -am 'Add feature'
6. Push: git push origin feature-name
7. Submit a Pull Request

Troubleshooting

Permission Denied

If you get permission errors when killing processes:

# Linux/macOS - may need sudo for system processes
sudo pcr kill 80

# Windows - run as Administrator

Command Not Found (lsof, ss, netstat)

Linux:

sudo apt-get install net-tools iproute2 lsof

macOS: Tools are pre-installed. If missing:

xcode-select --install

Windows: Tools are pre-installed with Windows.

Process Still Running After Kill

Try force kill:

pcr kill 8080 --force

Or increase grace period in config:

grace_period_ms = 5000

Platform Coverage

Note: Tests run on macOS. Cross-platform code uses conditional compilation (#[cfg(target_os = "...")]).

Roadmap

• Package managers (Homebrew, Chocolatey, AUR)
• Shell completions (bash, zsh, fish)
• Watch mode (auto-kill on port binding)
• Port conflict history/logs
• TUI with real-time monitoring
• Docker container support
• Remote process management

Support

• Report bugs: GitHub Issues
• Documentation: TESTING.md
• Discussions: GitHub Discussions

Made with ❤️ for developers tired of port conflicts