CLI Reference

CLI Reference

Hydra provides a unified CLI with subcommands for different trading modes. The CLI is available as a pre-built binary or via bun run when running from source.

Unified CLI

hydra <command> [options]

Commands

Command	Description
run	Start the trading bot (paper/live/replay)
trades	View trade history and statistics
record	Record market data for later replay
reset	Reset bot state (breaker, all)
tui	Launch TUI dashboard
latency	Check network latency to exchanges
version	Show version information
help	Show help message

Global Options

Option	Description
--config, -c <path>	Path to config file

---

reset

Reset bot state to recover from kill switch or clear all state.

hydra reset [options]

Options

Option	Description	Default
--breaker	Clear breaker/kill state only	-
--all	Reset ALL state (dangerous)	-
--mode, -m <mode>	Trading mode: paper or live	live
--config, -c <path>	Path to config file	-
--db <path>	Explicit path to state database	Auto-detected
-y, --yes	Skip confirmation prompt	false

Examples

# Clear breaker state to allow bot restart (live mode)
hydra reset --breaker

# Clear breaker state (paper mode)
hydra reset --breaker --mode paper

# Clear breaker with specific config
hydra reset --breaker --config ./my-config.yaml

# Full reset - clears ALL state (DANGEROUS)
hydra reset --all

# Skip confirmation (for scripts)
hydra reset --breaker -y

When to Use

The bot persists its kill/breaker state to SQLite. When the breaker is triggered (via SIGINT, risk limit breach, or manual kill), the bot will refuse to trade on restart until the breaker state is cleared.

Use --breaker to:

• Recover after pressing Ctrl+C to stop the bot
• Resume after a risk limit triggered the kill switch
• Clear state after investigating a kill event

Use --all to:

• Start completely fresh (resets peak equity, P&L, cost basis)
• Warning: This will break P&L calculations if you have open positions!

---

run

Start the trading bot in paper, live, or replay mode.

hydra run [options]

Options

Option	Description	Default
--mode, -m <mode>	Trading mode: paper, live, or replay	paper
--verbose, -v	Enable verbose logging	false
--config, -c <path>	Path to config file	./config.example.yaml

Environment Variables

Variable	Description	Default
BOT_CONFIG	Path to config file (alternative to —config)	./config.example.yaml

Examples

# Binary
hydra run                           # Paper trading (default)
hydra run --mode live               # Live trading
hydra run --mode replay             # Replay recorded session
hydra run --config ./my-config.yaml # Custom config
hydra run --verbose                 # Verbose logging

# From source
bun run paper                       # Paper trading
bun run bot                         # Full bot (mode from config)
BOT_CONFIG=./config.yaml bun run bot

Output

Trading sessions create a directory under persistence.outDir:

out/
└── run_1234567890/
    └── events.jsonl     # All events for replay/analysis

---

trades

View trade history and statistics from the append-only trade ledger.

hydra trades [options]

Options

Option	Description	Default
--mode, -m <mode>	Trade mode: paper or live	paper
--limit, -n <count>	Limit number of trades shown	All
--market <id>	Filter by market ID	None
--side <side>	Filter by side: BUY or SELL	None
--summary	Show summary statistics only	false
--json	Output as JSON for parsing	false

Examples

# Binary
hydra trades                    # Show all paper trades
hydra trades --mode live        # Show live trades
hydra trades -n 20              # Show last 20 trades
hydra trades --summary          # Show trade statistics
hydra trades --side SELL        # Show only sells
hydra trades --json             # Output as JSON

# From source
bun run trades
bun run trades -- --mode live

---

record

Record live market data for later replay.

hydra record [options]

Options

Option	Description
--config, -c <path>	Path to config file

Examples

# Binary
hydra record
hydra record --config ./my-config.yaml

# From source
bun run record

Output

Recording creates JSONL files containing all market events:

out/
└── record_1234567890/
    └── recording.jsonl   # All market data events

---

tui

Real-time monitoring dashboard for running bot instances.

hydra tui [options]

Options

Option	Description
--config, -c <path>	Path to config file (for IPC connection settings)

Keyboard Shortcuts

Key	Action
q	Quit dashboard
?	Toggle help modal
a	Arm/disarm (required before control commands)
k	Send kill command to bot (armed mode)
p	Pause trading (armed mode)
r	Resume trading (armed mode)
c	Cancel all open orders (armed mode)
↑/↓	Navigate markets
l	Toggle log format (raw/formatted)
s	Toggle auto-scroll
PgUp/PgDn	Scroll logs (when auto-scroll off)

Example

# Start bot in one terminal
hydra run
# or from source: bun run paper

# Connect TUI in another terminal
hydra tui
# or from source: bun run tui

---

latency

Check network latency to exchange APIs and WebSockets.

hydra latency [options]

Options

Option	Description	Default
-e, --exchange <name>	Specific exchange: binance, polymarket, coinbase	All
-s, --samples <n>	Number of REST samples	10
--ws-samples <n>	Number of WebSocket samples	5
-h, --help	Show help

Examples

# Binary
hydra latency                    # Check all exchanges
hydra latency -e binance         # Check Binance only
hydra latency --samples 20       # More samples for accuracy

# From source
bun run latency

Output

Provides latency statistics and deployment recommendations:

Binance:
  Best REST latency: 45.2ms
  Best WebSocket latency: 38.1ms

✅ Excellent Binance WebSocket latency (38.1ms)
   Your location is well-suited for latency arbitrage.

---

version

Show version and build information.

hydra version

Output

Hydra v0.1.0
  Build target: bun-linux-arm64
  Build time:   2024-01-15T10:30:00.000Z

---

IPC Commands

The bot exposes an IPC server for remote control. Commands can be sent via WebSocket or through the TUI.

Available Commands

Command	Description
kill	Emergency stop - closes all positions and shuts down
pause	Pause trading (keep connections alive)
resume	Resume trading after pause
cancel_all	Cancel all open orders

WebSocket Example

const ws = new WebSocket('ws://127.0.0.1:9876');

ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'kill' }));
};

ws.onmessage = (event) => {
  const snapshot = JSON.parse(event.data);
  console.log('State snapshot:', snapshot);
};

---

Exit Codes

Code	Meaning
0	Clean shutdown (user requested or session complete)
1	Error (config error, connection failure, etc.)

---

Signals

Signal	Behavior
SIGINT (Ctrl+C)	Graceful shutdown - saves state, closes connections
SIGTERM	Same as SIGINT