DevPort CLI

A command-line tool for managing development server ports across multiple projects.

Overview

When working on multiple development projects, port conflicts are a common issue. DevPort CLI helps you track and manage which ports are being used by which projects, making it easy to avoid conflicts and organize your development environment.

Features

• 🚀 Simple port registration: Register ports with project names and descriptions
• 📋 List all registered ports: View all ports in use across your projects
• 🔍 Find port information: Quickly check what's using a specific port
• 💡 Smart port suggestions: Get suggestions for available ports
• 🗑️ Easy removal: Remove port registrations when projects are no longer active
• 🏠 Local storage: All data stored locally in your home directory

Installation

Global installation via npm

npm install -g devport-cli

Local development

git clone https://github.com/uehara/devport-cli.git
cd devport-cli
npm install
npm link

Usage

Add a port registration

devport add 3000 my-react-app
devport add 3001 my-api-server --description "Express.js API server"

List all registered ports

devport list
# or
devport ls

Find information about a specific port

devport find 3000

Get a suggestion for an available port

devport suggest
devport suggest --start 4000

Scan directory and auto-register ports

# Scan current directory
devport scan

# Scan specific directory
devport scan ~/projects

# Scan with custom depth (default: 3)
devport scan ~/projects --depth 5

# Preview what would be registered (dry run)
devport scan ~/projects --dry-run

# Include low-confidence matches
devport scan ~/projects --all

This command automatically scans your project directories and detects ports from:

• package.json scripts (Next.js, Vite, React, etc.)
• .env files
• Configuration files (vite.config.js, next.config.js, etc.)
• Docker compose files
• Server files (server.js, app.js, etc.)

Remove a port registration

devport remove 3000
# or
devport rm 3000

Kill a process using a specific port

devport kill 3000

This command will find and terminate the process that is currently using the specified port. This is useful when you have a stuck development server or process that didn't shut down properly.

Kill all processes for a specific project

devport kill-project my-react-app

This command will find and terminate all processes using ports registered to the specified project name.

Kill all processes for all registered ports

devport kill-all

This command will find and terminate all processes using any of your registered ports. Useful for cleaning up all development servers at once.

Clear all registrations

devport clear

View help

devport --help
devport <command> --help

Commands

| Command | Alias | Description | | ----------------------- | ----- | --------------------------------------------------- | | add <port> <project> | - | Register a port for a project | | remove <port> | rm | Remove a port registration | | list | ls | List all registered ports | | find <port> | - | Find information about a specific port | | suggest | - | Suggest an available port | | scan [directory] | - | Scan directory and auto-detect/register ports | | kill <port> | - | Kill the process using the specified port | | kill-project <name> | - | Kill all processes for the specified project | | kill-all | - | Kill all processes for all registered ports | | clear | - | Clear all port registrations |

Options

add command

• -d, --description <desc>: Add a description for the project

suggest command

• -s, --start <port>: Starting port number for suggestions (default: 3000)

scan command

• -d, --depth <levels>: Maximum directory depth to scan (default: 3)
• --all: Include low-confidence port matches
• --dry-run: Preview what would be registered without actually registering

Data Storage

DevPort CLI stores all port registrations locally in:

• macOS/Linux: ~/.devport/ports.json
• Windows: %USERPROFILE%\.devport\ports.json

Use Cases

Daily Development

# Auto-detect ports in your projects directory
devport scan ~/projects

# Starting a new React project
devport add 3000 my-new-app --description "React development server"

# Need a port for API server
devport suggest --start 3001
# Returns: Suggested available port: 3001
devport add 3001 my-api

# Check what's using port 3000
devport find 3000

# View all active projects
devport list

AI Integration

# Get an available port for AI to use
AVAILABLE_PORT=$(devport suggest)
devport add $AVAILABLE_PORT "ai-generated-project" --description "Auto-generated by AI"

Project Cleanup

# Kill stuck React development server on specific port
devport kill 3000

# Kill all processes for a specific project
devport kill-project my-react-app

# Kill all registered development servers at once
devport kill-all

# Remove port when project is done
devport remove 3000

# Clean slate
devport clear

Requirements

• Node.js 14.0.0 or higher
• npm or yarn

Contributing

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

License

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

AI Assistant Instructions

For AI Assistants (Claude, ChatGPT, etc.):

When users are developing projects and need port management, use the devport CLI tool:

Essential Commands:

• devport scan <directory> - Auto-detect and register ports from project files
• devport suggest - Get available port suggestion before starting new projects
• devport add <port> <project-name> --description "<desc>" - Register port usage
• devport list - Show all registered ports to avoid conflicts
• devport find <port> - Check what's using a specific port
• devport kill <port> - Kill process using the specified port (useful for stuck servers)
• devport kill-project <name> - Kill all processes for a specific project
• devport kill-all - Kill all processes for all registered ports
• devport remove <port> - Clean up when project ends

AI Workflow Integration:

1. When working with existing projects: Run devport scan <directory> to auto-detect all ports
2. Before starting any development server: Run devport suggest to get available port
3. When creating projects: Always register the port with devport add
4. When port conflicts occur: Use devport list and devport find to troubleshoot, or devport kill to terminate stuck processes
5. In automation scripts: Use AVAILABLE_PORT=$(devport suggest) for dynamic port allocation

Best Practices for AI:

• Always check port availability before suggesting specific ports to users
• Register ports immediately when setting up development environments
• Include port cleanup in project completion instructions
• Use descriptive project names and descriptions for better port management

Support

If you encounter any problems or have suggestions, please open an issue on GitHub.