CLI Reference
Complete reference for the portzero command-line interface.
Running apps
PortZero can run commands as managed apps. When the first argument is a known executable (in $PATH or ./node_modules/.bin), the app name is inferred from the current directory. Otherwise, the first argument is the app name and the rest is the command.
| Command | Description |
|---|
portzero <command> | Run command, name inferred from cwd |
portzero <name> <command> | Run command with explicit name |
portzero run <name> <command...> | Explicit form (supports --no-restart) |
portzero up | Start all apps from portzero.toml |
portzero down | Stop all running apps |
portzero list | List active apps and URLs |
portzero logs <name> [-n lines] [-f] | Tail logs for an app |
portzero run
# Explicit run with auto-restart disabled
portzero run my-app --no-restart pnpm dev
# Shorthand (equivalent, but auto-restart is on by default)
portzero my-app pnpm dev
portzero logs
# Show last 50 lines
portzero logs my-app -n 50
# Follow logs in real time
portzero logs my-app -f
Daemon management
| Command | Description |
|---|
portzero start | Start the proxy daemon (foreground) |
portzero start -d | Start in background (daemonize) |
portzero stop | Stop the daemon |
portzero status | Show daemon status |
Mocking
Mock rules let you return synthetic responses without hitting the upstream server. You can manage mocks from the desktop app (recommended) or via the CLI.
| Command | Description |
|---|
portzero mock add <app> <method> <path> | Create a new mock rule |
portzero mock list [--app <name>] | List all mock rules |
portzero mock enable <id> | Enable a mock rule |
portzero mock disable <id> | Disable a mock rule |
portzero mock delete <id> | Delete a mock rule |
portzero mock add options
| Flag | Description | Default |
|---|
--status <code> | Response status code | 200 |
--body <string> | Response body (inline) | empty |
--body-file <path> | Response body from file | -- |
-H, --header <header> | Response header (Key: Value), repeatable | -- |
# Mock a health check endpoint
portzero mock add api GET /health --status 200 \
--body '{"status":"ok"}' \
-H "Content-Type: application/json"
# Mock a 404 for a specific path
portzero mock add api GET /old-endpoint --status 404
# Mock with a body from file
portzero mock add api POST /webhook --body-file ./fixtures/webhook.json
# List mocks for a specific app
portzero mock list --app api
# Disable and delete
portzero mock disable abc123
portzero mock delete abc123
Network simulation
Test how your app behaves under degraded network conditions. Configure network simulation from the desktop app (sliders per-app) or via the CLI.
| Command | Description |
|---|
portzero throttle set <app> | Set network simulation for an app |
portzero throttle list | List active network simulation profiles |
portzero throttle clear <app> | Clear network simulation for an app |
portzero throttle set options
| Flag | Description |
|---|
--latency <ms> | Fixed latency in milliseconds |
--jitter <ms> | Random jitter +/- ms (requires --latency) |
--drop <0.0-1.0> | Packet loss probability |
--bandwidth <bytes/s> | Bandwidth limit in bytes per second |
--path <glob> | Only apply to matching paths |
# Add 200ms latency with 50ms jitter
portzero throttle set my-app --latency 200 --jitter 50
# Simulate 10% packet loss
portzero throttle set my-app --drop 0.1
# Limit bandwidth and add latency
portzero throttle set my-app --latency 100 --bandwidth 51200
# Only throttle a specific path
portzero throttle set my-app --latency 500 --path "/api/slow/*"
# List active profiles
portzero throttle list
# Clear simulation
portzero throttle clear my-app
Certificates
portzero trust # Install CA certificate into system trust store
portzero untrust # Remove it
Public tunnels (Coming Soon)
Public tunnel support is planned for a future release. When available, the share subcommand will expose local apps to the internet.
| Command | Description |
|---|
portzero share start <app> [--subdomain] [--relay] | Expose an app via public tunnel |
portzero share stop <app> | Stop sharing an app |
portzero share list | List active tunnels |
MCP server (Coming Soon)
MCP server for AI agent integration is planned for a future release.