Skip to main content

​
Overview

The portless get command constructs and prints the URL for a service using the same hostname and worktree logic as portless run, without actually starting the service. This is useful for wiring services together or passing URLs as environment variables.

​
Syntax

portless get <name> [options]

​
Parameters

​
name
string
required
The service name to construct a URL for. Uses the same naming logic as portless run including git worktree detection.

​
Options

​
--no-worktree
boolean
Skip git worktree prefix detection and use only the base name. Useful when you want the plain URL regardless of which worktree you’re in.
​
--help, -h
boolean
Show help information for the get command.

​
Examples

​
Basic Usage

Get the URL for a service: 
portless get backend
# Output: http://backend.localhost:1355

​
In a Git Worktree

When run from a linked worktree on branch auth: 
portless get backend
# Output: http://auth.backend.localhost:1355

​
Skip Worktree Detection

Force the base URL without worktree prefix: 
portless get backend --no-worktree
# Output: http://backend.localhost:1355

​
Wiring Services Together

Use portless get to pass URLs as environment variables: 
# Set backend URL for frontend dev server
BACKEND_URL=$(portless get backend) npm run dev

# In a script
export API_URL=$(portless get api)
export AUTH_URL=$(portless get auth)
pnpm dev

​
Use Cases

Environment Variables

Pass service URLs to applications that need to communicate with other portless services

Scripts

Build shell scripts that reference portless service URLs without hardcoding

CI/CD

Generate URLs in automation workflows that mirror local development setup

Documentation

Display service URLs in documentation or help messages

​
How It Works

The portless get command:
  1. Discovers state - Reads the proxy port and configuration
  2. Applies worktree logic - Detects if you’re in a git worktree and prepends the branch name as a subdomain
  3. Constructs URL - Builds the complete .localhost URL
  4. Prints to stdout - Outputs only the URL (no extra formatting) so it can be captured in shell variables
portless get does not check if the service is actually running. It simply constructs what the URL would be if the service were running with that name.

​
Comparison with portless list

Featureportless getportless list
PurposeConstruct URL for any nameShow active routes
Checks if runningNoYes
Output formatPlain URL onlyFormatted table
Git worktree awareYesNo
Use in scriptsYes (stdout only)No (formatted output)

​
Error Handling

​
Missing Service Name

portless get
Error: Missing service name. Solution: Provide a service name as the first argument.

​
Unknown Flag

portless get backend --unknown
Error: Unknown flag "--unknown". Solution: Use only supported flags: --no-worktree, --help

portless run

Run a service with auto-inferred name

portless list

Show all active routes

Git Worktrees

Learn about worktree detection

Build docs developers (and LLMs) love

Get started for freeTalk to us