portk

A surgical port killer - find and terminate processes using specific ports.

Features

• Port investigation - Instantly see what's running on any port
• Process tree view - Visualize parent/child process relationships
• Parent chain - Trace process ancestry back to init
• Detailed info - View memory, CPU, uptime, command, and more
• Surgical kill - Terminate just the process or the entire tree
• Port scanning - Scan common development ports at once
• Interactive mode - Explore and act on processes interactively

Installation

Quick Install (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/yigiterdev/portk/main/install.sh | sh

From crates.io

cargo install portk

From GitHub

cargo install --git https://github.com/yigiterdev/portk

From source

git clone https://github.com/yigiterdev/portk.git
cd portk
cargo install --path .

Pre-built binaries

Download the latest release for your platform from Releases.

Manual binary installation

# macOS (Apple Silicon)
curl -LO https://github.com/yigiterdev/portk/releases/latest/download/portk-aarch64-apple-darwin.tar.gz
tar xzf portk-aarch64-apple-darwin.tar.gz
sudo mv portk /usr/local/bin/

# Linux (x64)
curl -LO https://github.com/yigiterdev/portk/releases/latest/download/portk-x86_64-unknown-linux-gnu.tar.gz
tar xzf portk-x86_64-unknown-linux-gnu.tar.gz
sudo mv portk /usr/local/bin/

Usage

Quick Check

portk 3000

Output:

info: Found 1 process on port 3000:

╭──────┬───────┬─────────┬─────────┬────────╮
│ Port │ PID   │ Process │ Address │ State  │
├──────┼───────┼─────────┼─────────┼────────┤
│ 3000 │ 21974 │ node    │ *:3000  │ LISTEN │
╰──────┴───────┴─────────┴─────────┴────────╯

Scan Common Ports

portk --scan

Scans ports commonly used in development: 3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 9000, and more.

Detailed Process Info

portk 3000 --info

Output:

info: Process Details:

  PID: 21974
  Name: node
  User: ahmetyigiter
  CWD: /Users/ahmetyigiter/projects/myapp
  Memory: 81.8 MB
  CPU: 0.0%
  Uptime: 22h 46m
  Command:
    node server.js

View Process Tree

portk 3000 --tree

Output:

info: Process Tree:

[21974] node (81.8MB) node server.js
├── [21980] node (45.2MB) node worker.js
└── [21981] node (32.1MB) node watcher.js

View Parent Chain

portk 3000 --parents

Output:

info: Parent Chain:

[21974] node
  ↳ [21964] node
    ↳ [21949] node
      ↳ [5114] zsh
        ↳ [2404] Terminal
          ↳ [1] launchd

Kill a Process

portk 3000 --kill           # Graceful kill (SIGTERM)
portk 3000 --kill --force   # Force kill (SIGKILL)
portk 3000 --kill-tree      # Kill process and all children

Non-Interactive Mode

portk 3000 --kill -y        # Kill without confirmation

All Options

Usage: portk [OPTIONS] [PORT]

Arguments:
  [PORT]  Port number to investigate (e.g., 3000, 8080)

Options:
  -s, --scan       Scan common development ports
  -t, --tree       Show process tree for the port's process
  -p, --parents    Show parent chain (ancestors) of the process
  -k, --kill       Kill the process using this port
  -f, --force      Force kill (SIGKILL instead of SIGTERM)
      --kill-tree  Kill entire process tree
  -y, --yes        Non-interactive mode (no confirmations)
  -i, --info       Show detailed process information
  -h, --help       Print help
  -V, --version    Print version

Common Scenarios

"What's using port 3000?"

portk 3000

"Kill whatever is on port 8080"

portk 8080 --kill -y

"See all active dev servers"

portk --scan

"Debug a stuck process"

portk 3000 --info --tree --parents

"Nuclear option - kill everything related to port 3000"

portk 3000 --kill-tree --force -y

How It Works

1. Port Detection: Uses lsof (macOS) or ss/netstat (Linux) to find processes bound to ports
2. Process Info: Uses the sysinfo crate to gather detailed process information
3. Process Tree: Builds parent/child relationships by scanning /proc (Linux) or using system APIs
4. Kill Signals: Sends SIGTERM (graceful) or SIGKILL (force) to terminate processes

Platform Support

License

MIT License - see LICENSE for details.

Contributing

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

Development Setup

# Clone the repo
git clone https://github.com/yigiterdev/portk.git
cd portk

# Install pre-commit hooks
./scripts/setup-hooks.sh

# Build and test
cargo build
cargo test

The pre-commit hook will automatically run cargo fmt --check and cargo clippy before each commit.

Creating a Release

To create a new release:

1. Update version in Cargo.toml
2. Commit the change: git commit -am "Bump version to x.y.z"
3. Create a tag: git tag vx.y.z
4. Push with tags: git push && git push --tags

GitHub Actions will automatically build binaries for all platforms and create a release.