CLI Reference

RoxyProxy is controlled entirely from the command line. Running roxyproxy with no arguments launches an interactive terminal menu. All commands follow the pattern:

roxyproxy <command> [options]

start

Start the proxy server in the foreground.

roxyproxy start [options]

Option	Default	Description
`--port <number>`	`8080`	Proxy listening port
`--ui-port <number>`	`8081`	Web UI and API port
`--db-path <path>`	`~/.roxyproxy/data.db`	SQLite database location

# Default ports
roxyproxy start

# Custom ports
roxyproxy start --port 9000 --ui-port 9001

# Custom database location
roxyproxy start --db-path /tmp/proxy.db

The process writes its PID to ~/.roxyproxy/pid and responds to SIGINT/SIGTERM for graceful shutdown.

stop

Stop the running proxy server.

roxyproxy stop [options]

Option	Default	Description
`--ui-port <number>`	`8081`	API port to send shutdown request to

Sends a graceful shutdown request via the API. Falls back to SIGTERM via the PID file if the API is unreachable.

roxyproxy stop
roxyproxy stop --ui-port 9001

status

Show proxy status.

roxyproxy status [options]

Option	Default	Description
`--ui-port <number>`	`8081`	API port to query

roxyproxy status

Example output:

Status     Running
Proxy      port 8080
Requests   142
DB Size    3.2MB

requests

Query captured requests from the database. This is the most powerful command in RoxyProxy.

roxyproxy requests [options]

Option	Default	Description
`--host <pattern>`		Filter by hostname (substring match)
`--status <code>`		Filter by HTTP status code
`--method <method>`		Filter by HTTP method
`--search <pattern>`		Search URLs (substring match)
`--since <time>`		After this time (Unix ms or ISO date)
`--until <time>`		Before this time (Unix ms or ISO date)
`--limit <n>`	`100`	Maximum number of results
`--format <format>`	`table`	Output format: `table`, `json`, or `agent`
`--tail`		Stream new requests in real-time (interactive TUI)
`--ui-port <number>`	`8081`	UI/API port (used with `--tail`)
`--db-path <path>`	`~/.roxyproxy/data.db`	Database location

Filter aliases

Shorthand flags for common queries:

Alias	Description
`--failed`	Show only 4xx and 5xx responses
`--last-hour`	Requests from the last hour
`--last-day`	Requests from the last 24 hours
`--slow <ms>`	Requests slower than threshold (in milliseconds)

Output formats

The default output is a human-readable table. Use --format json for piping to jq or feeding to scripts. Use --format agent for LLM-optimized output that is compact and structured for AI consumption.

Examples

# All 500 errors
roxyproxy requests --status 500

# POST requests to a specific host
roxyproxy requests --host api.example.com --method POST

# Search URLs
roxyproxy requests --search "/api/v2"

# Limit results
roxyproxy requests --format table --limit 20

# Time-bounded query
roxyproxy requests --since "2024-01-15T00:00:00Z" --until "2024-01-16T00:00:00Z"

# JSON for piping to jq
roxyproxy requests --format json --host stripe.com | jq '.data[].url'

# LLM-optimized output
roxyproxy requests --format agent --failed

# Only failed requests from the last hour
roxyproxy requests --failed --last-hour

# Slow requests from the last day
roxyproxy requests --slow 1000 --last-day

# Combine aliases with other filters
roxyproxy requests --failed --host api.example.com --last-hour

Real-time tailing

The --tail flag launches an interactive terminal UI that streams new requests as they arrive:

# Tail all traffic (auto-starts proxy + system proxy if needed)
roxyproxy requests --tail

# Tail with filters
roxyproxy requests --host todoist.com --tail
roxyproxy requests --status 500 --tail
roxyproxy requests --method POST --host api.example.com --tail

What --tail does automatically:

Starts the proxy if it is not already running
Enables the macOS system proxy so all traffic routes through RoxyProxy
Opens an interactive TUI with arrow-key navigation
On quit (Ctrl+C), disables the system proxy and stops the proxy it started

TUI keyboard shortcuts

Key	Action
`Up` / `Down`	Navigate requests
`Enter`	View full request detail (headers, body)
`Esc`	Back to list from detail view
`g` / `G`	Jump to top (newest) / bottom (oldest)
`Ctrl+C`	Quit (cleans up proxy and system proxy)

New requests auto-scroll to the top. Scrolling down disables auto-scroll; pressing g re-enables it.

To get raw JSON streaming instead of the TUI, use --format json --tail.

request

Show full details of a single captured request, including headers and bodies.

roxyproxy request <id> [options]

Option	Default	Description
`--format <format>`	`json`	Output format: `json` or `table`
`--db-path <path>`	`~/.roxyproxy/data.db`	Database location

roxyproxy request a1b2c3d4-e5f6-7890-abcd-ef1234567890
roxyproxy request a1b2c3d4-e5f6-7890-abcd-ef1234567890 --format table

clear

Delete all captured traffic from the database.

roxyproxy clear [options]

Option	Default	Description
`--ui-port <number>`	`8081`	API port

roxyproxy clear

trust-ca

Install and trust the RoxyProxy CA certificate for HTTPS interception.

roxyproxy trust-ca [options]

Option	Description
`--no-interactive`	Skip prompts; print cert path and manual instructions

# Interactive (prompts for sudo password)
roxyproxy trust-ca

# Non-interactive (CI, scripts)
roxyproxy trust-ca --no-interactive

uninstall-ca

Remove the RoxyProxy CA certificate from the system trust store.

roxyproxy uninstall-ca [options]

Option	Description
`--no-interactive`	Skip prompts; print removal instructions

# Interactive (prompts for sudo password)
roxyproxy uninstall-ca

# Non-interactive
roxyproxy uninstall-ca --no-interactive

On macOS, removes via security remove-trusted-cert. On Linux, removes from /usr/local/share/ca-certificates/ and refreshes the store. Only available when the certificate is currently installed.

proxy-on

Configure RoxyProxy as the system-wide HTTP/HTTPS proxy. macOS only.

roxyproxy proxy-on [options]

Option	Default	Description
`--port <number>`	`8080`	Proxy port
`--service <name>`	auto-detected	Network service (e.g., "Wi-Fi", "Ethernet")

roxyproxy proxy-on
roxyproxy proxy-on --port 9000 --service "Wi-Fi"

proxy-off

Remove RoxyProxy from system proxy settings. macOS only.

roxyproxy proxy-off [options]

Option	Default	Description
`--service <name>`	auto-detected	Network service

roxyproxy proxy-off

Getting Started - Install and capture your first request
REST API - Programmatic access to captured traffic
Configuration - Config file, storage limits, and auto-cleanup
HTTPS Interception - CA trust setup for trust-ca and uninstall-ca commands
AI Agent Plugin - Uses --format agent for AI-optimized output

← Getting Started Web UI →