Commands

Run an app

portless run [--name <name>] <cmd> [args...]
portless <name> <cmd> [args...]

portless run infers the project name from package.json, git root, or directory name. Use --name to override the inferred name while still applying worktree prefixes.

portless <name> uses an explicit name with no inference or prefixing.

portless run next dev                    # infer name from project
portless run --name myapp next dev       # override inferred name
portless myapp next dev                  # explicit name
portless api pnpm start
portless docs.myapp next dev

Flag	Description
`--name <name>`	Override the inferred base name (worktree prefix still applies). Only for `portless run`.
`--app-port <number>`	Use a fixed port for the app instead of auto-assignment. Also configurable via `PORTLESS_APP_PORT`.
`--force`	Override an existing route registered by another process

Get a service URL

portless get <name>

Print the URL for a service. Useful for wiring services together in scripts or env vars:

BACKEND_URL=$(portless get backend)

Applies worktree prefix detection by default. Use --no-worktree to skip it.

Alias (static routes)

portless alias <name> <port>
portless alias <name> <port> --force
portless alias --remove <name>

Register a route for a service not managed by portless (e.g. a Docker container). Aliases persist across stale-route cleanup.

portless alias my-postgres 5432     # -> https://my-postgres.localhost
portless alias redis 6379           # -> https://redis.localhost
portless alias --remove my-postgres # remove the alias

List routes

portless list

Shows active routes and their assigned ports.

Trust the CA

portless trust

Adds the portless certificate authority to your system trust store. Required once for HTTPS with auto-generated certs.

Proxy control

Start

portless proxy start

Flag	Description
`-p, --port <number>`	Proxy port (default: 443, or 80 with `--no-tls`). Auto-elevates with sudo.
`--no-tls`	Disable HTTPS (use plain HTTP on port 80)
`--https`	Enable HTTPS (default, accepted for compatibility)
`--tld <tld>`	Use a custom TLD instead of `.localhost` (e.g. `test`). Auto-syncs `/etc/hosts` for custom TLDs.
`--cert <path>`	Custom TLS certificate
`--key <path>`	Custom TLS private key
`--foreground`	Run in foreground instead of daemon mode

Stop

portless proxy stop

Hosts

portless hosts sync     # add current routes to /etc/hosts
portless hosts clean    # remove portless entries from /etc/hosts

Auto-enabled for custom TLDs. For .localhost, set PORTLESS_SYNC_HOSTS=1 to enable.

Bypass portless

PORTLESS=0 pnpm dev

Runs the command directly without the proxy.

Info

portless --help
portless --version