kilar 0.2.4

A powerful CLI tool for managing port processes - quickly find and terminate processes using specific ports
Documentation

kilar 🔌

CI Release Crates.io Downloads License Rust Version

A powerful CLI tool for managing port processes on your system. Quickly find and terminate processes using specific ports with an intuitive interface.

📋 Table of Contents

🚀 Quick Start

# Install via Homebrew (macOS/Linux)
brew tap polidog/kilar && brew install kilar

# Install via Cargo
cargo install kilar

# Quick usage
kilar check 3000        # Check if port 3000 is in use
kilar kill 3000         # Kill process on port 3000
kilar list              # List all ports in use

✨ Key Features

🔍 Smart Port Detection

  • Lightning-fast port checking - Instantly see if a port is in use and which process owns it
  • Protocol support - Works with both TCP and UDP protocols
  • Detailed process information - View PID, process name, and command line

⚡ Safe Process Management

  • Graceful termination - Kill processes with built-in safety confirmations
  • Force kill option - Override confirmations when needed
  • Interactive selection - Choose multiple processes to terminate with an intuitive UI

📊 Comprehensive Listing

  • Port range filtering - View specific port ranges (e.g., 3000-4000)
  • Process name filtering - Find ports by application name
  • Flexible sorting - Sort by port, PID, or process name

🎨 Developer-Friendly Output

  • Color-coded terminal output - Easy-to-read with intuitive color schemes
  • JSON export - Perfect for scripting and automation
  • Verbose mode - Get detailed information when troubleshooting

🌍 Cross-Platform & Modern

  • Universal compatibility - Works on macOS and Linux
  • Multiple installation methods - Homebrew, Cargo, or from source
  • Zero dependencies - Single binary with no runtime requirements

📦 Installation

🍺 Homebrew (Recommended for macOS/Linux)

# Add tap and install
brew tap polidog/kilar
brew install kilar

# Or one-liner
brew install polidog/kilar/kilar

📦 Cargo (Universal)

# Install from crates.io
cargo install kilar

# Install from source
cargo install --git https://github.com/polidog/kilar.git

📥 Binary Downloads

Download pre-built binaries from the releases page:

  • macOS (Intel): kilar-x86_64-apple-darwin.tar.gz
  • macOS (Apple Silicon): kilar-aarch64-apple-darwin.tar.gz
  • Linux (x86_64): kilar-x86_64-unknown-linux-gnu.tar.gz
  • Linux (ARM64): kilar-aarch64-unknown-linux-gnu.tar.gz

🔨 From Source

git clone https://github.com/polidog/kilar.git
cd kilar
cargo build --release
sudo cp target/release/kilar /usr/local/bin/

Note: Requires Rust 1.70 or later

Usage 🚀

Check if a port is in use

# Check port 3000
kilar check 3000

# Check UDP port
kilar check 5353 -p udp

# JSON output
kilar check 3000 --json

# Verbose mode for detailed information
kilar check 3000 -v

Kill a process using a specific port

# Kill process on port 3000
kilar kill 3000

# Force kill without confirmation
kilar kill 3000 --force

# Kill UDP process
kilar kill 5353 -p udp

List all ports in use

# List all TCP ports
kilar list

# List all ports (TCP and UDP)
kilar list -p all

# Filter by port range
kilar list -r 3000-4000

# Filter by process name
kilar list -f node

# Sort by different criteria
kilar list -s pid    # Sort by PID
kilar list -s name   # Sort by process name
kilar list -s port   # Sort by port number (default)

# Interactive kill mode
kilar list          # Select processes to kill interactively
kilar list --view-only  # Just view, no kill option

Command Options 🎛️

Global Options

  • -q, --quiet: Suppress output
  • -j, --json: Output in JSON format
  • -v, --verbose: Enable verbose output
  • -h, --help: Print help information
  • -V, --version: Print version information

Check Command

kilar check <PORT> [OPTIONS]
  • PORT: Port number to check
  • -p, --protocol <PROTOCOL>: Protocol (tcp/udp) [default: tcp]

Kill Command

kilar kill <PORT> [OPTIONS]
  • PORT: Port number of the process to kill
  • -f, --force: Force kill without confirmation
  • -p, --protocol <PROTOCOL>: Protocol (tcp/udp) [default: tcp]

List Command

kilar list [OPTIONS]
  • -r, --ports <RANGE>: Port range to filter (e.g., 3000-4000)
  • -f, --filter <NAME>: Filter by process name
  • -s, --sort <ORDER>: Sort order (port/pid/name) [default: port]
  • -p, --protocol <PROTOCOL>: Protocol (tcp/udp/all) [default: tcp]
  • --view-only: View only (no kill feature)

Examples 📝

Development Workflow

# Check if your development server port is free
kilar check 3000

# If occupied, see what's using it
kilar check 3000 -v

# Kill the process if needed
kilar kill 3000

# List all development-related ports
kilar list -r 3000-9000 -f node

System Administration

# List all services
kilar list -p all

# Find specific service
kilar list -f nginx

# Check system ports
kilar list -r 1-1024

# Export port usage as JSON
kilar list --json > ports.json

Output Format 🎨

Standard Output

  • ✓ Green checkmark: Success/Port in use
  • × Red cross: Error/Failed operation
  • ○ Blue circle: Information/Port available
  • Yellow: Port numbers and process names
  • Cyan: PIDs and labels
  • Blue: Protocol information

JSON Output

All commands support JSON output for scripting and automation:

{
  "port": 3000,
  "protocol": "tcp",
  "status": "occupied",
  "process": {
    "pid": 12345,
    "name": "node",
    "command": "node server.js"
  }
}

Requirements 📋

System Tools

kilar requires one of the following system tools to detect port usage:

  • lsof (recommended) - Usually pre-installed on macOS, optional on Linux
  • ss (Linux fallback) - Part of iproute2 package, typically pre-installed on most Linux distributions
  • netstat (alternative fallback) - Available on most systems

Installation instructions for Linux:

# Arch Linux / Manjaro
sudo pacman -S lsof  # Optional, ss is already available via iproute2

# Debian / Ubuntu
sudo apt-get install lsof  # Optional, ss is already available

# Fedora / RHEL / CentOS
sudo dnf install lsof  # Optional, ss is already available

Note: On Linux systems without lsof, kilar automatically uses ss as a fallback. Only processes owned by the current user will be shown unless running with elevated privileges.

Permissions

  • Some port detection operations may require elevated privileges to see all processes
  • Process termination requires appropriate permissions for the target process

Building from Source 🔨

# Clone the repository
git clone https://github.com/polidog/kilar.git
cd kilar

# Build in release mode
cargo build --release

# Run tests
cargo test

# Install locally
cargo install --path .

🤝 Contributing

We welcome contributions! Here's how you can help:

See our Contributing Guide for detailed instructions.

🔐 Security

kilar handles system processes and requires appropriate permissions:

  • Process visibility: Requires read access to system process information
  • Process termination: May require elevated privileges (sudo) for some processes
  • Network data: Accesses network connection information through system commands

For security issues, please see our Security Policy.

📈 Project Status

🏗️ Development Status

  • Stable: Core functionality is production-ready with v0.1.1 released
  • Active: Regular updates and maintenance
  • Cross-platform: Tested on macOS, Linux, and Windows
  • Package Distribution: Available via Homebrew, Cargo, and GitHub Releases

🚀 CI/CD Status

CI

Note: This tool is designed for Unix-like systems (macOS and Linux) and provides comprehensive port management functionality on these platforms.

📊 Performance & Compatibility

Platform Min Version Status Notes
macOS 10.15+ ✅ Full Support Intel & Apple Silicon
Linux Any modern ✅ Full Support Requires lsof

🗺️ Roadmap

✅ Completed (v0.1.x)

  • v0.1.0: Core port management functionality
  • v0.1.1: Improved Homebrew distribution and bug fixes

🔮 Future Releases

  • v0.2.0: Configuration file support
  • v0.3.0: Plugin system for custom output formats
  • v0.4.0: Network interface filtering
  • v1.0.0: Stable API and comprehensive documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors & Contributors

🚀 Maintainer: polidog

Thanks to all contributors who help make this project better!

🙏 Acknowledgments

  • 🦀 Built with Rust - For memory safety and performance
  • ⚡ Tokio - Async runtime for efficient I/O operations
  • 🎨 Terminal UI - Powered by dialoguer and colored
  • 🏗️ Cross-compilation - Thanks to GitHub Actions and cross

🔗 Related Projects & Resources

🛠️ System Tools Used

  • lsof - List open files (Unix)
  • netstat - Network statistics (Windows)
  • ss - Socket statistics (Linux)

📦 Distribution Channels

⚠️ Important: This tool requires appropriate permissions to view and terminate processes. Some system processes may require elevated privileges (sudo).