portmap

A CLI tool for managing local service port mappings. Track which ports are assigned to which services, check for conflicts, and integrate with Docker Compose files.

Installation

Download the binary from the releases section

or

# Clone the repository
git clone https://github.com/GameTec_live/portmap-cli.git
cd portmap-cli

# Install dependencies
bun install

# Link globally
bun link

Usage

portmap <command> [arguments]

Commands

Add a Service

portmap add [port] [name]

• portmap add - Find next free port, prompt to save
• portmap add 3000 - Register port 3000, prompt for name
• portmap add 3000 MyAPI - Register MyAPI on port 3000
• portmap add 3000,3001 MyApp - Register MyApp on multiple ports

List Services

portmap list [--enabled|--disabled]
portmap get [port|name]

• portmap list - Show all services in a table
• portmap list --enabled - Show only active services
• portmap list --disabled - Show only disabled services
• portmap get 3000 - Get service name for port 3000
• portmap get MyAPI - Get port(s) for MyAPI

Delete a Service

portmap del <port|name>
portmap rm <port|name>

Enable/Disable Services

portmap enable <port|name>
portmap disable <port|name>

Temporarily disable a service without removing it from the database.

Check Port Usage

portmap check [--all] [--delete-stale|--disable-stale]

Verify which registered services are actually running:

• portmap check - Interactive mode, prompt for each stale service
• portmap check --all - Include disabled services in check
• portmap check --delete-stale - Auto-delete services not in use
• portmap check --disable-stale - Auto-disable services not in use

A service is considered "in use" if at least one of its ports is occupied.

Export/Import

portmap export [file] [--enabled|--disabled]
portmap import <file> [--skip|--overwrite]

Export services to JSON:

portmap export                    # Output to stdout
portmap export backup.json        # Export to file
portmap export --enabled out.json # Export only enabled services

Import services from JSON:

portmap import backup.json             # Interactive (prompt on conflicts)
portmap import backup.json --skip      # Skip conflicting entries
portmap import backup.json --overwrite # Replace conflicting entries

JSON format:

{
  "version": 1,
  "services": [
    { "name": "my-api", "ports": [3000, 3001], "enabled": true },
    { "name": "old-service", "ports": [8080], "enabled": false }
  ]
}

Docker Compose Integration

portmap <compose-file>

Parse a docker-compose.yml or compose.yml file and register all port mappings:

portmap docker-compose.yml
portmap ./myproject/compose.yaml

Features:

• Extracts host ports from all services
• Supports all port formats: "3000", "8080:80", "3000-3002:3000-3002", "127.0.0.1:8080:80"
• Names services as <parent-folder>-<service-name>
• Checks for conflicts with system ports and existing registrations
• Options on conflict: ignore, abort, or auto-replace with next free ports

Environment Variables

Variable	Description
PORTMAP_DB	Path to database file (default: ~/.portmap.db)
NO_COLOR	Disable colored output when set

Examples

# Register a new API service
portmap add 3000 MyAPI

# Register a service with multiple ports
portmap add 8080,8443 WebServer

# Find the next available port
portmap add

# List all services
portmap list

# Check what's actually running
portmap check

# Disable services that aren't running
portmap check --disable-stale

# Back up your port mappings
portmap export ~/portmap-backup.json

# Restore on a new machine
portmap import ~/portmap-backup.json --overwrite

# Import ports from a Docker Compose project
portmap docker-compose.yml

How It Works

• Database: SQLite database stored at ~/.portmap.db (configurable)
• Port checking: Uses Bun.listen() to test if ports are available
• Multi-port support: Services can have multiple ports (stored as comma-separated values)
• Enable/disable: Temporarily disable services without losing the mapping

Requirements

• Bun runtime