portsage

Crates.ioportsage
lib.rsportsage
version0.1.1
created_at2025-05-10 08:28:55.967634+00
updated_at2025-06-12 01:44:14.561051+00
descriptionA TUI tool to monitor processes and their listening ports
homepage
repositoryhttps://github.com/mei28/PortSage
max_upload_size
id1668201
size2,257,076
Mingzhe Yang (mei28)

documentation

README

🚀 PortSage - Process + Port Explorer

PortSage is a sleek TUI (Terminal User Interface) tool that helps you:

  • 🧭 Explore processes on your machine
  • 🔍 Filter by name, command, PID, or port
  • 📍 View ports associated with each process
  • 🪄 Inspect process details in a floating modal
  • 🗑️ Kill processes interactively with confirmation dialog
  • 📋 Copy PID to clipboard with one key

✨ Features

📊 Process Overview

  • Lists all processes
  • Shows PID, name, ports, and command line
  • Port-bound processes are sorted to the top

🎯 Filter Mode

  • Press : to enter filter mode
  • Matches against name, command, and PID

🔎 Detail Mode

  • Press Tab to open process detail window

  • Shows full metadata including:

    • CPU usage, memory
    • Executable path
    • Current working directory
    • Listening ports

📋 Copy PID

  • Press Enter to copy the selected PID to clipboard
  • Confirmation message appears for 2 seconds

❌ Kill Process

  • Press x to open confirmation dialog
  • Press y to kill the process (SIGKILL)
  • Press n or Esc to cancel
  • ✅ Success message shown after killing

🎮 Key Bindings

Key Action
j / Down Move down
k / Up Move up
: Enter filter mode
Tab Show detail
Enter Copy PID to clipboard
x Kill process (confirm)
q / Esc Quit

🛠️ Install & Run

cargo build --release
./target/release/portsage --tui

📦 Install from crates.io

cargo install portsage
portsage --tui

❄️ Install via Nix Flakes

nix run github:mei28/PortSage

📦 CLI Options

USAGE:
    portsage [OPTIONS]

OPTIONS:
    -c, --cli               Use CLI mode (non-interactive)
    -f, --filter <STRING>   Filter keyword
    -p, --port <PORT>       Filter by port
        --json              Output as JSON (CLI mode only)
        --kill <PID>        Kill process by PID
        --tui               Launch interactive TUI (default)

🧪 Requirements

  • 🦀 Rust 1.70+
  • Linux/macOS (requires lsof)

🎯 Examples

TUI Mode (Default)

# Launch interactive TUI
portsage
# or explicitly
portsage --tui

CLI Mode

# List all processes with ports
portsage --cli

# Filter by process name
portsage --cli --filter nginx

# Filter by port
portsage --cli --port 8080

# Output as JSON
portsage --cli --json

# Kill a process
portsage --kill 1234
Commit count: 24

cargo fmt