CLI Reference¶
Usage¶
Global Options¶
| Flag | Description |
|---|---|
--config, -c |
Config file path (default: prox.yaml) |
--addr |
API address for client commands (auto-discovered from .prox/prox.state) |
--detach, -d |
Run in background (daemon mode) |
Commands¶
up¶
Start processes. By default runs in the foreground; use --detach for background/daemon mode.
| Flag | Description |
|---|---|
--detach, -d |
Run in background (daemon mode) |
--tui |
Enable interactive TUI mode (foreground only, mutually exclusive with --detach) |
--api-port, -p |
Override API server port (otherwise dynamic) |
--http-port |
Override proxy HTTP port |
--https-port |
Override proxy HTTPS port |
--no-proxy |
Disable proxy even if configured |
Examples:
# Start all processes (foreground)
prox up
# Start in background (daemon mode)
prox up -d
# Start specific processes
prox up web api
# Start with TUI (foreground only)
prox up --tui
# Start specific processes with TUI
prox up --tui web api
# Override API port
prox up --api-port 6000
# Daemon mode with specific port
prox up -d --api-port 6000
# Start with HTTP proxy only
prox up --http-port 6788
# Start with dual-stack proxy
prox up --http-port 6788 --https-port 6789
Dynamic Port Allocation:
When no port is specified (via --api-port or api.port in config), prox automatically finds an available port. The port is stored in .prox/prox.state and auto-discovered by CLI commands.
status¶
Show process status.
| Flag | Description |
|---|---|
--json |
Output as JSON |
Examples:
logs¶
Show or stream logs.
| Flag | Description |
|---|---|
-f, --follow |
Stream logs continuously |
-n, --lines |
Number of lines (default: 100) |
--process |
Filter by process name |
--pattern |
Filter by pattern (substring match) |
--regex |
Treat pattern as regex |
--json |
Output as JSON |
Examples:
# Show last 100 lines
prox logs
# Show last 50 lines from api process
prox logs --process api --lines 50
# Stream all logs
prox logs -f
# Stream logs from api
prox logs -f --process api
# Filter for errors
prox logs --pattern ERROR
# Regex filter
prox logs --pattern "GET|POST" --regex
# JSON output for piping
prox logs -f --json | jq .
start¶
Start a stopped process.
Examples:
stop¶
Stop the running prox instance or a specific process.
Without arguments, sends a shutdown signal to the daemon. All processes receive SIGTERM, then SIGKILL after a timeout.
With a process name, stops only that process while keeping prox and other processes running.
Examples:
down¶
Alias for stop (without arguments). Provides symmetry with prox up --detach.
attach¶
Attach TUI to a running daemon. Opens an interactive terminal UI connected via the API.
Examples:
# Start daemon
prox up -d
# Attach TUI to running daemon
prox attach
# TUI operations work the same as `prox up --tui`
# Press q to detach (daemon continues running)
Connection Errors:
If the daemon stops while the TUI is attached, the TUI will show a connection error. Press q to quit, then restart the daemon with prox up -d.
restart¶
Restart a specific process.
Examples:
requests¶
Show or stream proxy requests.
| Flag | Description |
|---|---|
-f, --follow |
Stream requests continuously |
-n, --limit |
Number of requests to show (default: 100) |
--subdomain |
Filter by subdomain |
--method |
Filter by HTTP method (GET, POST, etc.) |
--min-status |
Filter by minimum status code (e.g., 400 for errors) |
--json |
Output as JSON |
Examples:
# Show recent requests
prox requests
# Stream requests in real-time
prox requests -f
# Filter by subdomain
prox requests --subdomain api
# Filter by HTTP method
prox requests --method GET
# Show only errors (4xx and 5xx)
prox requests --min-status 400
# JSON output for piping
prox requests --json | jq .
Request IDs:
Each request is assigned a short hash ID (7 characters, git-style). These IDs are displayed in the output and can be used to reference specific requests.
version¶
Show version information.
help¶
Show help for any command.