🚀 killport

A lightweight, blazing-fast CLI utility written in Go to quickly find and terminate processes running on specific network ports.

Never write complex lsof -i :3000 and kill -9 <PID> chains again.

---

✨ Features

• ⚡ Zero Dependencies: Compiles to a single static binary with no external runtimes needed.
• 🔍 Reliable Lookup: Uses system-level port diagnostics to locate active process PIDs.
• 🐳 Docker Integration: Automatically detects if a port is occupied by a Docker container and shows you how to terminate it.
• 🛡️ Safety Guard: Automatically prevents self-termination if the tool is somehow matching its own process.
• 🎨 Clear Console Logs: Reports how many processes/containers were found, their details, and termination status.

---

🚀 Installation & Usage

Since killport is compiled into a single static binary with no external dependencies, you do not need Go installed on your machine to run it.

1. Installation

Option A: One-Line Shell Installer (Recommended for Linux/macOS)

Run the following command to automatically download the correct pre-compiled binary for your operating system and architecture, and install it to /usr/local/bin:

curl -fsSL https://raw.githubusercontent.com/Harshidpatel12/killport/main/install.sh | bash

The script auto-detects your OS and CPU architecture, downloads the correct pre-compiled binary from the Releases page, and installs it to /usr/local/bin.

Option B: Manual Binary Download (Zero Dependencies)

1. Navigate to the Releases page.
2. Download the compressed archive matching your operating system and CPU architecture (e.g., killport-linux-amd64.tar.gz).
3. Extract the archive and copy the binary to your system PATH:

   tar -xvf killport-linux-amd64.tar.gz
   chmod +x killport
   sudo mv killport /usr/local/bin/

Option C: Via Package Managers (Coming Soon)

• macOS (Homebrew):

  brew install Harshidpatel12/tap/killport

• Ubuntu/Debian (APT):

  sudo apt install killport

Option D: Via Go (For developers with Go installed)

If you have Go installed on your machine, you can download, compile, and install it directly from source:

go install github.com/Harshidpatel12/killport@latest

---

2. Usage

To kill any local process running on port 3000:

killport 3000

Example Output (Local Process):

Searching for processes on port 3000...
Found 1 process(es) on port 3000: 12345
Killing process with PID 12345...
Successfully killed process 12345.

Example Output (Docker Container):

If the port is occupied by one or more running Docker containers, killport will detect them instead of attempting to terminate host-level proxy processes:

Port 3000 is occupied by Docker container(s):
  - Container 'my-web-app' (ID: 8655be0e4e81)

To kill the container(s), run:
  killport --container my-web-app

Terminating Docker Containers

You can terminate Docker containers directly by passing their name, ID, or the published port:

# Kill by container name or ID
killport --container my-web-app
killport -c 8655be0e4e81

# Or kill all containers occupying port 3000
killport --container 3000

---

🛠️ Development & Linting

This project uses standard Go tools and pre-commit hooks to maintain code style and quality.

Local Setup

1. Clone the project.
2. Initialize pre-commit hooks (requires pre-commit installed):

   pre-commit install

Run Tests Locally

go test -v ./...

📦 Creating a Release

This project uses GoReleaser to automatically build cross-platform binaries and upload them to GitHub Releases.

To publish a new release, tag a commit with a version and push:

git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

This triggers the Release GitHub Action, which compiles binaries for Linux (amd64/arm64) and macOS (amd64/arm64) and uploads them to the GitHub Releases page automatically. The install.sh script will then download the correct binary for the user's system.

---

📄 License

Distributed under the MIT License. See LICENSE for more information.