Portly

Modern CLI tool for managing local development ports

Portly helps you understand what's running on your ports with beautiful tables, framework detection, Docker integration, and interactive process management.

Cross-platform support: Windows, macOS, Linux

Features

🔍 Port Scanning - List all listening ports with process information
🎯 Framework Detection - Automatically detect Next.js, Rust, Python, Docker, and more
🐳 Docker Integration - Identify Docker containers and their frameworks
📊 Process Management - Kill processes by port or PID, clean orphaned processes
👀 Watch Mode - Real-time monitoring of port changes
📝 JSON Output - Machine-readable output for scripting
⚙️ Configuration - Customize filters, colors, and defaults

Installation

Quick Install (Recommended)

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/sabry-awad97/portly/main/scripts/install.ps1 | iex

Unix-like (bash):

curl -sSL https://raw.githubusercontent.com/sabry-awad97/portly/main/scripts/install.sh | bash

The installer will:

Download the latest release from GitHub
Install to %LOCALAPPDATA%\portly\bin (Windows) or ~/.local/bin (Unix)
Add to your PATH automatically
Verify installation succeeded

Install Specific Version

Windows:

# Download and run with version parameter
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/sabry-awad97/portly/main/scripts/install.ps1" -OutFile "install.ps1"
.\install.ps1 -Version "0.1.0"

Unix:

curl -sSL https://raw.githubusercontent.com/sabry-awad97/portly/main/scripts/install.sh | bash -s 0.1.0

From Source

git clone https://github.com/sabry-awad97/portly
cd portly
cargo build --release

The binary will be at target/release/portly.exe

Uninstall

Windows:

iwr -useb https://raw.githubusercontent.com/sabry-awad97/portly/main/scripts/uninstall.ps1 | iex

Unix:

curl -sSL https://raw.githubusercontent.com/sabry-awad97/portly/main/scripts/uninstall.sh | bash

Add --remove-config flag to also remove configuration files.

Quick Start

# List all listening ports
portly

# Show detailed information for a specific port
portly details 3000

# Kill a process by port
portly kill 3000

# Watch for port changes in real-time
portly watch

# List all dev processes (not just port-bound)
portly ps

Commands

`portly` or `portly list`

List all listening ports with process information.

portly
portly list
portly list --all      # Include system processes
portly list --json     # JSON output

Example output:

PORT   PROCESS          PID    FRAMEWORK    PROJECT
3000   node.exe         12345  Next.js      my-app
5432   postgres.exe     5678   PostgreSQL   [Docker]
8080   rust.exe         9012   Rust         portly

`portly details <port>`

Show detailed information about a specific port.

portly details 3000
portly details 3000 --no-prompt  # Skip kill confirmation
portly details 3000 --json

Shows:

Process name and PID
Command line
Memory usage
Uptime
Working directory
Git branch (if in a git repo)
Process tree
Interactive kill prompt

`portly kill <targets...>`

Kill processes by port or PID.

portly kill 3000           # Kill process on port 3000
portly kill 3000 5000      # Kill multiple ports
portly kill 12345          # Kill by PID
portly kill 3000 -f        # Force kill (SIGKILL)

`portly clean`

Find and kill orphaned/zombie processes.

portly clean              # Dry-run (show what would be killed)
portly clean --execute    # Actually kill orphaned processes

`portly ps`

List all development processes (not just port-bound).

portly ps
portly ps --all     # Include system processes
portly ps --json

Shows:

All Node.js, Python, Rust, Go processes
Docker containers
CPU and memory usage
Color-coded by CPU usage (red >25%, yellow >5%, green ≤5%)

`portly watch`

Watch for port changes in real-time.

portly watch
portly watch -i 5    # Update every 5 seconds (default: 2)

Shows:

Timestamp for each change
NEW ports (green)
CLOSED ports (red)
Press Ctrl+C to stop

`portly config`

Manage configuration.

portly config init    # Create default config file
portly config path    # Show config file location
portly config reset   # Reset to defaults

Configuration

Config file location: %APPDATA%\portly\config.toml

Default Configuration

[display]
colors = true
compact = false

[filters]
exclude_system = true
exclude_processes = [
    "Spotify",
    "Chrome",
    "Firefox",
    "Slack",
    "Discord",
    "Code",
    "Teams",
]

[defaults]
show_all = false
json_output = false

Customization

Edit the config file to:

Exclude specific processes from listings
Disable colors for piping to files
Change default flags

Global Flags

These flags work with all commands:

--json - Output in JSON format
--all - Show all processes (including system)
--no-color - Disable colored output
--ascii - Use ASCII-only output (no Unicode symbols)
--verbose or -v - Show detailed output with full descriptions
--quiet - Suppress progress indicators

ASCII Mode

For terminals without Unicode support or CI/CD environments:

portly list --ascii
portly ps --ascii
portly watch --ascii

ASCII mode replaces:

Status bullets: ● → *
Watch markers: ▲ → ^, ▼ → v
Success/error: ✓ → +, ✗ → x
Table borders: Unicode → ASCII
Process tree: │ → |, ├─ → +-, └─ → +-

Verbose Mode

For debugging, troubleshooting, or when you need complete information:

portly list --verbose    # or -v
portly ps --verbose      # or -v
portly watch --verbose   # or -v

Verbose mode provides:

No truncation - Full command lines displayed
Extended columns - MEMORY, CPU%, UPTIME, DIRECTORY
Full paths - Complete directory paths instead of project names
Complete data - All available process metadata

Example verbose list output:

PORT   PROCESS   PID    FRAMEWORK   STATUS    MEMORY   CPU%   UPTIME   DIRECTORY                    WHAT
3000   node.exe  12345  Next.js     healthy   245.3MB  12.5%  2h 15m   C:\Users\dev\projects\app    node C:\Users\dev\projects\app\server.js --port 3000

Combine flags:

portly list --verbose --ascii    # Verbose output with ASCII symbols
portly ps -v --json              # Verbose JSON output
portly watch -v --no-color       # Verbose without colors

Framework Detection

Portly automatically detects:

Next.js - next dev, next start
Vite - vite, vite dev
Rust - cargo run, cargo watch
Python - python, uvicorn, flask, django
Go - go run
Docker - PostgreSQL, Redis, nginx, MongoDB, MySQL, RabbitMQ, Elasticsearch

Docker Integration

Portly integrates with Docker to:

Identify containers by port
Detect framework from Docker image
Group Docker processes in ps output

Graceful degradation: Works without Docker installed.

Examples

Find what's using port 3000

portly details 3000

Kill all Node.js processes on specific ports

portly kill 3000 3001 3002

Monitor ports during development

portly watch

Export port list to JSON

portly list --json > ports.json

Find and clean orphaned processes

portly clean --execute

See all dev processes with CPU usage

portly ps

Debug with verbose output

# See full command lines and all process details
portly list --verbose

# Verbose output with full paths
portly ps -v

# Watch with complete information
portly watch --verbose

Use in CI/CD or legacy terminals

# ASCII-only output for maximum compatibility
portly list --ascii

# Combine with other flags
portly ps --ascii --json

Troubleshooting

# See everything: verbose + all processes
portly list --verbose --all

# Debug specific port with full details
portly details 3000 --verbose

# Monitor with complete command lines
portly watch -v

Development

Prerequisites

Rust 1.85+ (2024 Edition)
Windows 10+

Build

cargo build

Test

cargo test

Lint

cargo clippy -- -W clippy::all

Format

cargo fmt

Architecture

Portly follows Clean Architecture principles:

Platform Abstraction - Cross-platform support via platform trait
Deep Modules - Small interfaces, deep implementations
TDD - All features built with test-driven development
No Unsafe - Pure safe Rust throughout

Project Structure

portly/
├── src/
│   ├── main.rs           # Entry point and command orchestration
│   ├── cli.rs            # Clap command definitions
│   ├── scanner.rs        # Port scanning orchestration
│   ├── process.rs        # Process information types
│   ├── framework.rs      # Framework detection
│   ├── display.rs        # Table/JSON output formatting
│   ├── details.rs        # Port details view
│   ├── config.rs         # Configuration management
│   ├── docker.rs         # Docker integration (async Bollard)
│   ├── error.rs          # Error types
│   ├── colors.rs         # Color utilities
│   ├── progress.rs       # Progress indicators
│   ├── typo.rs           # Command typo suggestions
│   ├── commands/         # Command handlers
│   │   ├── mod.rs        # Command module exports
│   │   ├── list.rs       # List ports command
│   │   ├── details.rs    # Port details command
│   │   ├── kill.rs       # Kill process command
│   │   ├── clean.rs      # Clean orphaned processes
│   │   ├── ps.rs         # List dev processes
│   │   ├── watch.rs      # Watch port changes
│   │   └── config.rs     # Config management commands
│   ├── platform/         # Platform abstraction
│   │   ├── mod.rs        # Platform trait
│   │   ├── native.rs     # Cross-platform implementation
│   │   └── mock.rs       # Mock for testing
│   └── snapshots/        # Snapshot tests (insta)
├── tests/                # Integration tests
├── scripts/              # Installation scripts
├── docs/                 # Documentation
└── issues/               # Local issue tracking

Contributing

Contributions welcome! Please:

Fork the repository at github.com/sabry-awad97/portly
Create a feature branch
Follow Rust conventions
Write tests for new features
Run cargo clippy and cargo fmt
Update documentation
Submit a pull request

Roadmap

Cross-platform support (macOS, Linux)
Process filtering by name/pattern
Port history tracking
Export to various formats (CSV, HTML)
Web UI for monitoring

License

MIT License - see LICENSE file for details

Acknowledgments

Built with:

clap - Command line parsing
tabled - Table formatting
sysinfo - System information
netstat2 - Network socket information
colored - Terminal colors

Made with ❤️ for developers who need to manage their ports

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
docs		docs
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Portly

Features

Installation

Quick Install (Recommended)

Install Specific Version

From Source

Uninstall

Quick Start

Commands

portly or portly list

portly details <port>

portly kill <targets...>

portly clean

portly ps

portly watch

portly config

Configuration

Default Configuration

Customization

Global Flags

ASCII Mode

Verbose Mode

Framework Detection

Docker Integration

Examples

Find what's using port 3000

Kill all Node.js processes on specific ports

Monitor ports during development

Export port list to JSON

Find and clean orphaned processes

See all dev processes with CPU usage

Debug with verbose output

Use in CI/CD or legacy terminals

Troubleshooting

Development

Prerequisites

Build

Test

Lint

Format

Architecture

Project Structure

Contributing

Roadmap

License

Acknowledgments

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`portly` or `portly list`

`portly details <port>`

`portly kill <targets...>`

`portly clean`

`portly ps`

`portly watch`

`portly config`