CLI Reference

CLI Reference

Ocular has three main modes: TUI (interactive dashboard), CLI (terminal output), and setup (interactive wizard).

---

TUI Mode (Default)

ocular                      # Load config, show dashboard
ocular -c /path/to/config.toml  # Custom config path
ocular --demo               # Simulated traffic, skip dashboard

The TUI launches a dashboard where you select a proxy group, then enter the main view with the event stream, component pane, and detail inspector.

---

CLI Subcommands

Skip the TUI entirely. Output events directly to the terminal.

ocular proxy

Start a proxy and output events to stdout.

ocular proxy <protocol> [host[:port]] [options]

Examples:

# Auto-assign listen port (3306 + 10000 = 13306)
ocular proxy mysql 192.168.0.184

# Equivalent explicit form
ocular proxy mysql 192.168.0.184:3306 -l 0.0.0.0:13306

# Minimal — defaults to 127.0.0.1 with protocol's default port
ocular proxy redis
# ↳ listens on 0.0.0.0:16379, forwards to 127.0.0.1:6379

# Custom listen port
ocular proxy postgres 10.0.0.5 -l :25432

ocular capture (alias: cap)

Passively capture traffic from a network interface.

ocular capture <protocol> [host[:port]] [options]
ocular cap <protocol> [host[:port]] [options]    # shorthand

Examples:

# Capture on default interface (auto-detected)
sudo ocular capture mysql 192.168.0.184

# Specify interface
sudo ocular capture redis 192.168.0.184 -i en0

# Local traffic
sudo ocular capture redis 127.0.0.1 -i lo0    # macOS
sudo ocular capture redis 127.0.0.1 -i lo     # Linux

ocular setup

Launch the interactive setup wizard.

ocular setup

7-step guided flow: mode → protocol → location → address → connectivity → confirm → add more.

---

Output Format Options

Flag	Description
--json	Output as JSON (one object per line)
--raw	No ANSI colors (auto-enabled when stdout is not a TTY)
--color	Force colored output
--tui, -t	Launch minimal TUI preview from CLI subcommands

JSON Output

ocular proxy mysql --json

Each line is a JSON object:

{"timestamp":"2026-05-28T10:30:45Z","component":"mysql","protocol":"mysql","command":"SELECT * FROM users LIMIT 5","full_command":"SELECT * FROM users LIMIT 5","response":"ResultSet (5 rows, 5 cols)","response_detail":"...","latency_ms":3.73,"process":null,"src":"127.0.0.1:54321","dest":"127.0.0.1:3306","system":false}

Raw Output (for logging)

ocular proxy mysql 192.168.0.184 --raw >> events.log

TUI Preview from CLI

ocular proxy redis --tui
# Full TUI features (vim nav, visual select, yank, filter)
# No component pane, `q` exits directly

---

Common Flags

Flag	Description
-i, --interface	Network interface for capture mode
-l, --listen	Listen address (default: 0.0.0.0:<remote_port+10000>)
-c, --config	Path to config file
-h, --help	Show help
-V, --version	Show version

-l supports :port shorthand (binds to 0.0.0.0):

ocular proxy postgres 10.0.0.5 -l :25432
# ↳ equivalent to -l 0.0.0.0:25432

---

Default Ports

Protocol	Default Port	Proxy Listen Port
Redis	6379	16379
MySQL	3306	13306
PostgreSQL	5432	15432
RabbitMQ (AMQP)	5672	15672
MongoDB	27017	37017
HTTP/Elasticsearch	9200	19200
Memcached	11211	21211
Kafka	9092	19092

---

Scripting Examples

Count queries per type

ocular proxy mysql --json 2>/dev/null | jq -r '.command' | \
  awk '{print $1}' | sort | uniq -c | sort -rn

Find slow queries (>100ms)

ocular proxy postgres --json 2>/dev/null | \
  jq 'select(.latency_ms > 100)'

Record and replay

# Record
ocular proxy redis --json --raw > traffic.jsonl

# Analyze later
cat traffic.jsonl | jq '.command' | sort | uniq -c

CI integration

# Start proxy in background
ocular proxy mysql --json > events.json &
PROXY_PID=$!

# Run tests against proxy port
pytest --db-port=13306

# Check results
kill $PROXY_PID
cat events.json | jq '.latency_ms' | sort -n | tail -5