Skip to main content

​
Global Flags

These flags work with all commands:

​
--help, -h

Show help information for a command. 
portless --help              # General help
portless run --help          # Help for 'run' command
portless proxy --help        # Help for 'proxy' command

​
--version, -v

Show the installed version of Portless. 
portless --version
portless -v

​
App Running Flags

These flags work with portless run and portless <name> commands:

​
--force

Override an existing route registered by another process. 
portless run --force next dev
portless myapp --force next dev
Without --force, you’ll get an error if a route is already registered: 
Error: Route "myapp" is already registered by PID 12345.
With --force, the old route is replaced with the new one.

​
--app-port <number>

Use a fixed port for the app instead of automatic assignment (4000-4999 range). 
portless run --app-port 3000 next dev
portless myapp --app-port 8080 python -m http.server 8080
Port must be between 1 and 65535. Useful when:
  • Your app requires a specific port
  • You need to match a port in another config file
  • You’re debugging port-related issues

​
--name <name>

Force the use of a specific app name, bypassing subcommand dispatch. Useful for using reserved names. 
portless --name run next dev        # Use "run" as the app name
portless --name proxy node server.js  # Use "proxy" as the app name
Reserved names: run, get, alias, hosts, list, trust, proxy

​
--

Stop flag parsing. Everything after -- is passed directly to your command. 
portless run -- next dev --turbo
portless myapp -- vite --host 0.0.0.0
Useful when your command has flags that might conflict with Portless flags.

​
Proxy Flags

These flags work with portless proxy start:

​
--port <number>, -p <number>

Port for the proxy to listen on (1-65535). 
portless proxy start -p 8080
portless proxy start --port 3000
Ports below 1024 require sudo: 
sudo portless proxy start -p 80
sudo portless proxy start -p 443 --https
Default: 1355 (or value from PORTLESS_PORT environment variable)

​
--https

Enable HTTP/2 with TLS using auto-generated certificates. 
portless proxy start --https
On first run:
  1. Generates local CA
  2. Adds CA to system trust store (prompts for sudo on Linux)
  3. Generates wildcard certificate for *.localhost
Browsers will trust certificates without warnings.

​
--cert <path>

Path to a custom TLS certificate in PEM format. Must be used with --key. Implies --https. 
portless proxy start --cert ./cert.pem --key ./key.pem
Certificate must start with -----BEGIN CERTIFICATE-----.

​
--key <path>

Path to a custom TLS private key in PEM format. Must be used with --cert. Implies --https. 
portless proxy start --cert ./cert.pem --key ./key.pem
Key must start with -----BEGIN PRIVATE KEY----- or similar.

​
--no-tls

Disable HTTPS even if PORTLESS_HTTPS environment variable is set. 
export PORTLESS_HTTPS=1
portless proxy start --no-tls  # Overrides environment variable

​
--foreground

Run the proxy in the foreground instead of as a daemon. Useful for debugging. 
portless proxy start --foreground
Logs print to stdout/stderr. Press Ctrl+C to stop.

​
Alias Flags

These flags work with portless alias:

​
--force

Override an existing route when creating an alias. 
portless alias postgres 5432 --force

​
--remove

Remove an existing alias. 
portless alias --remove postgres

​
Get Flags

These flags work with portless get:

​
--no-worktree

Skip worktree prefix detection when generating the URL. 
# In a git worktree on branch "auth"
portless get backend
# -> http://auth.backend.localhost:1355

portless get backend --no-worktree
# -> http://backend.localhost:1355 (skips "auth" prefix)

​
Flag Placement

Flags can appear in different positions depending on the command:

​
Run Command

portless run --force --app-port 3000 next dev
portless run next dev --force  # Error: --force not recognized after command
Flags must come before the command.

​
Named Mode

portless --force myapp next dev       # Before name
portless myapp --force next dev       # After name
portless myapp next dev --force       # After name
Flags can come before or after the app name, but before the command.

​
With --

portless run --force -- next dev --turbo
portless myapp -- next dev --experimental-https
Everything after -- is passed to your command untouched.

​
Examples

​
Multiple Flags

# App running with force and fixed port
portless run --force --app-port 3000 next dev

# Proxy with custom port and HTTPS
sudo portless proxy start -p 443 --https

# Proxy with custom certs
portless proxy start --cert ./cert.pem --key ./key.pem

​
Flag Conflicts

# --https and --no-tls conflict (--no-tls wins)
portless proxy start --https --no-tls  # Starts without TLS

# --cert/--key implies --https (--no-tls has no effect)
portless proxy start --cert ./cert.pem --key ./key.pem --no-tls  # Still uses TLS

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us