🚀 PortMan TUI

A beautiful, modern Terminal User Interface (TUI) for managing ports on your system. Kill processes, find free ports, and monitor active connections - all with a stunning interface.

✨ Features

• 🎨 Beautiful TUI - Modern interface with gradients, animations, and smooth interactions
• 🔍 Real-time Search - Filter ports by number, process name, or PID
• ⚡ Kill Processes - Interactive process termination with confirmation
• 🔎 Find Free Ports - Quickly locate available ports in a range
• 🔄 Auto-refresh - Live monitoring of active ports
• 🌍 Cross-platform - Works on macOS, Linux (Ubuntu, Debian, Fedora, Arch), and Windows
• ⌨️ Keyboard Navigation - Full keyboard control for power users

📦 Installation

Global Installation (Recommended)

npm install -g portman-tui

Run without Installing

npx portman-tui

Local Installation

npm install portman-tui

🚀 Usage

Launch TUI

portman

Quick Commands

# List all active ports
portman list

# Kill process on specific port
portman kill 3000

# Find available port
portman find

# Find port in specific range
portman find --range 3000-4000

⌨️ Keyboard Shortcuts

| Key | Action | | ------- | ------------------------ | | / | Enter search mode | | ↑ ↓ | Navigate port list | | ← → | Toggle kill confirmation | | Enter | Select/Confirm | | ESC | Go back/Cancel | | Q | Quit application |

🎯 Use Cases

Development

• Quickly find which process is using port 3000
• Free up ports when switching between projects
• Monitor multiple services running simultaneously

DevOps

• Check port conflicts on servers
• Identify rogue processes
• Quick port management in CI/CD pipelines

System Administration

• Monitor network services
• Troubleshoot port binding issues
• Clean up orphaned processes

🛠️ Requirements

• Node.js >= 18.0.0
• Operating System: macOS, Linux, or Windows
• Permissions: May require sudo/admin rights to kill certain processes

📋 Platform-Specific Notes

macOS

Uses lsof command (pre-installed). No additional setup required.

Linux (Ubuntu/Debian/Fedora/Arch)

Uses lsof, ss, or netstat (usually pre-installed). If not available:

# Ubuntu/Debian
sudo apt-get install lsof net-tools

# Fedora/RHEL
sudo dnf install lsof net-tools

# Arch
sudo pacman -S lsof net-tools

Windows

Uses built-in netstat and tasklist commands. No additional setup required.

🏗️ Development

Setup

# Clone repository
git clone https://github.com/sidgaikwad/portman.git
cd portman

# Install dependencies
npm install

# Run in development mode
npm run dev

Scripts

npm run build        # Build TypeScript
npm run dev          # Run with tsx
npm run lint         # Run ESLint
npm run lint:fix     # Fix linting issues
npm run format       # Format code with Prettier
npm run format:check # Check formatting
npm run type-check   # TypeScript type checking
npm run clean        # Clean build directory

Project Structure

portman/
├── src/
│   ├── cli.tsx              # CLI entry point
│   ├── components/
│   │   ├── App.tsx          # Main application component
│   │   ├── Header.tsx       # Header with branding
│   │   ├── PortList.tsx     # Port listing component
│   │   ├── SearchBar.tsx    # Search interface
│   │   ├── KillConfirmation.tsx  # Kill dialog
│   │   └── Footer.tsx       # Keyboard shortcuts footer
│   └── utils/
│       └── portUtils.ts     # Port management logic
├── .github/
│   └── workflows/
│       ├── ci.yml           # CI pipeline
│       └── release.yml      # Release automation
├── package.json
├── tsconfig.json
└── README.md

Contributions are welcome! Please follow these steps:

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

Please make sure to:

• Follow the existing code style
• Run npm run lint and npm run format before committing
• Add tests for new features
• Update documentation as needed

📝 License

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

🙏 Acknowledgments

• Built with Ink - React for CLIs
• Inspired by modern TUI design principles
• Thanks to all contributors!

🐛 Issues

Found a bug? Have a feature request? Please open an issue.

📧 Contact

Your Name - @yourtwitter - [email protected]

Project Link: https://github.com/sidgaikwad/portman

Made with ❤️ by Your Name