wsup

A beautiful TUI localhost process manager with real-time graphs

---

wsup (pronounced "what's up") is a terminal UI for monitoring and managing processes running on localhost ports. Built with Rust and ratatui.

Features • Installation • Usage • Demo • Contributing

Demo

Basic Navigation & Sorting

Press s to cycle through sort modes, o to reverse order

CLI Flag: --sort

Start with a specific sort mode

CLI Flag: --filter

Start with processes pre-filtered, or use / to search

Detail View with Live Graphs

Press Enter on any process to see real-time metrics

Quick Start

# Install
cargo install wsup

# Run
wsup

# Run with options
wsup --sort cpu --filter node

# Quick look at what's on a port (no TUI)
wsup --port 3000

Features

• Live CPU/Memory/Connection graphs with 60-point history
• Sort by Port, CPU, Memory, Connections, or Name
• Filter processes as you type
• Color-coded ports (HTTP, databases, dev servers)
• Kill processes with confirmation
• One-shot --port lookup for scripting (no TUI, just the facts)
• Vim keybindings (j/k) support
• Auto-refresh every 2 seconds

Installation

Via Cargo

cargo install wsup

From Source

git clone https://github.com/NotKiwy/wsup.git
cd wsup
cargo install --path .

Usage

Basic Usage

# Start wsup
wsup

# Start with specific sort mode
wsup --sort cpu

# Start with a filter
wsup --filter node

# Both together
wsup --sort memory --filter 3000

# Quick kill process on port (without TUI)
wsup --kill 3000

# Quick info on what's listening on a port (without TUI)
wsup --port 3000

# Show help
wsup --help

CLI Flag: --port

wsup --port <PORT> is a one-shot, non-interactive mode: it looks up whatever process is listening on the given port, prints a compact summary, and exits immediately. It never opens the TUI, so it's safe to use in scripts or one-off terminal checks.

$ wsup --port 27017

       __      _____ _   _ _ __
       \ \ /\ / / __| | | | '_ \
        \ V  V /\__ \ |_| | |_) |
         \_/\_/ |___/\__,_| .__/
                          | |
                          |_|

┌─ Process Info ─────────────────────────────────────────────────┐
│                                                                │
│ mongod.exe                                                     │
│                                                                │
│ Port: :27017   PID: 5504   Protocol: TCP                       │
│                                                                │
│ CPU: 0.0%   Mem: 23M   Conn: 0                                 │
│                                                                │
│ Executable: C:\Program Files\MongoDB\Server\8.0\bin\mongod.exe │
│                                                                │
└────────────────────────────────────────────────────────────────┘

If nothing is listening on the port:

$ wsup --port 9999
Port 9999 is not in use.

If the process details can't be read (e.g. insufficient permissions), wsup prints a clear error to stderr and exits with a non-zero status instead of panicking.

Keyboard Shortcuts

List View

Key	Action
↑/k	Move up
↓/j	Move down
/	Search/filter
s	Cycle sort mode
o	Toggle sort order (ascending/descending)
Enter	Show process details
x or d	Kill selected process
r	Refresh processes
q	Quit

Detail View

Key	Action
Esc	Back to list
x	Kill process

Search Mode

Key	Action
Type	Filter processes
Backspace	Delete character
Esc or Enter	Exit search mode

Features Breakdown

Process List View

• Port Number - Color-coded by service type
• PID - Process identifier
• CPU % - Current CPU usage
• Memory - RAM consumption (formatted)
• Connections - Active network connections
• Name - Process name
• Command - Full command with arguments

Detail View

When you press Enter on a process, you get:

• Process Info - Name, port, PID, protocol, current stats, executable path
• CPU History Graph - Sparkline showing last 60 data points
• Memory History Graph - Visual memory usage trend
• Connections Graph - Active connections over time
• Command Display - Full command with all arguments

--port Summary (no TUI)

wsup --port <PORT> prints the same core facts as the Detail View, without starting the interactive interface:

• Process Name
• PID
• Port and Protocol (TCP/UDP)
• CPU Usage and Memory Usage
• Active Connections
• Executable Path (when available)

It reuses the exact same process-lookup and formatting code as the TUI, so the numbers always match.

Port Color Coding

• Cyan - HTTP/HTTPS (80, 443, 8080, 8443)
• Green - Dev servers (3000-3999)
• Magenta - Application servers (5000-5999)
• Red - Redis (6379)
• Blue - MongoDB (27017, 27018)
• Light Blue - PostgreSQL (5432, 5433)
• Light Magenta - MySQL (3306)
• Yellow - Various servers (8000-8999)

Technical Details

Built With

• ratatui - Terminal UI framework
• crossterm - Terminal manipulation
• sysinfo - System information
• clap - CLI argument parsing

Architecture

• Rust Edition 2021
• Zero unsafe code - Memory-safe by design
• 250ms event polling, 2s auto-refresh
• Process detection - Uses lsof for port mapping
• CPU metrics - Direct ps command integration

Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

Contributors

Stats

License

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

Acknowledgments

• Built with ratatui
• Inspired by htop, bottom, and glances
• Terminal recording with VHS

Why "wsup"?

wsup = "what's up" - A casual way to check on your localhost processes. Quick to type, easy to remember, shows you what's up on your ports.

---

If you find wsup useful:

• ⭐ Star this repository
• 🐛 Report bugs
• 💡 Suggest features
• 🔀 Contribute code

---

Made with ❤️ and Rust