Skip to main content

​
Overview

The alias command registers static routes for services not managed by Portless, such as Docker containers, databases, or external servers. Unlike routes created by portless run or portless <name>, aliases are not tied to a process and persist until explicitly removed.

​
Syntax

# Register an alias
portless alias <name> <port>

# Register with force
portless alias <name> <port> --force

# Remove an alias
portless alias --remove <name>

​
Parameters

​
<name>

The hostname for the service. Can include subdomains separated by dots.

​
<port>

The local port where the service is listening. Must be between 1 and 65535.

​
Options

​
--force

Override an existing route with the same name. 
portless alias postgres 5432 --force

​
--remove

Remove an existing alias. 
portless alias --remove postgres

​
--help, -h

Show help for the alias command. 
portless alias --help

​
Examples

​
Docker Services

# PostgreSQL container running on port 5432
portless alias postgres 5432
# -> http://postgres.localhost:1355

# Redis container on port 6379
portless alias redis 6379
# -> http://redis.localhost:1355

# MongoDB on port 27017
portless alias mongo 27017
# -> http://mongo.localhost:1355

​
External APIs

# Mock API server on port 8080
portless alias mockapi 8080
# -> http://mockapi.localhost:1355

# Legacy backend on port 3001
portless alias legacy-api 3001
# -> http://legacy-api.localhost:1355

​
With Subdomains

# Database for specific project
portless alias db.myapp 5432
# -> http://db.myapp.localhost:1355

# Cache service
portless alias cache.myapp 6379
# -> http://cache.myapp.localhost:1355

​
Override Existing Route

# Replace existing route
portless alias postgres 5433 --force

​
Remove Aliases

# Remove single alias
portless alias --remove postgres

# Remove multiple (run separately)
portless alias --remove redis
portless alias --remove mongo

​
Use Cases

​
Docker Compose

If you have services defined in docker-compose.yml with port mappings: 
services:
  postgres:
    image: postgres:15
    ports:
      - "5432:5432"

  redis:
    image: redis:7
    ports:
      - "6379:6379"
Register them with Portless: 
portless alias postgres 5432
portless alias redis 6379
Now your app can connect to http://postgres.localhost:1355 and http://redis.localhost:1355.

​
Static Mock Server

Run a mock API server separately, then alias it: 
# Start mock server
json-server --port 8080 db.json &

# Register with Portless
portless alias mockapi 8080

# Access at http://mockapi.localhost:1355

​
Microservices in Monorepo

If you have services that run independently but need stable URLs: 
# Service 1 always uses port 4001
portless alias auth 4001

# Service 2 always uses port 4002
portless alias api 4002

# Service 3 always uses port 4003
portless alias frontend 4003

​
Aliases vs Regular Routes

FeatureRegular Route (portless <name>)Alias (portless alias)
Process trackingYes (PID stored)No (PID is 0)
Auto-cleanupYes (when process exits)No (persists until removed)
Port assignmentAutomatic (4000-4999)Manual (you specify)
Use caseDev serversDocker, databases, static services

​
Listing Aliases

Aliases appear in portless list with (alias) label: 
portless list
Output: 
Active routes:

  http://postgres.localhost:1355  ->  localhost:5432  (alias)
  http://myapp.localhost:1355     ->  localhost:4123  (pid 12345)

​
Errors

​
Missing Arguments

portless alias myservice
# Error: Missing arguments.
# Usage:
#   portless alias <name> <port>

​
Invalid Port

portless alias myservice abc
# Error: Invalid port "abc". Must be 1-65535.

​
Alias Not Found

portless alias --remove nonexistent
# Error: No alias found for "nonexistent".

​
Route Conflict

If a route already exists (either from another process or another alias), use --force: 
portless alias myapp 8080
# Error: Route "myapp" is already registered by PID 12345.

# Override it
portless alias myapp 8080 --force

​
Exit Codes

  • 0 - Success
  • 1 - Error (invalid arguments, alias not found, route conflict without —force)

Build docs developers (and LLMs) love

Get started for freeTalk to us