Skip to content

CLI Reference

Command-line interface for the Arbiter-Bot engine.

Usage

cargo run --manifest-path arbiter-engine/Cargo.toml -- [OPTIONS]

Or if built:

./target/release/arbiter-engine [OPTIONS]

Options

Execution Modes

Flag Description
--dry-run Sign orders but don't submit (test API integration)
--paper-trade Simulate fills with position tracking
--backtest Replay historical data for backtesting
--check-connectivity Check exchange connectivity and exit
--record-data Record live market data to storage

Paper Trading Options

Flag Type Default Description
--fidelity basic|realistic basic Fill simulation fidelity level
--latency duration none Simulated network latency (e.g., 50ms)

Kalshi Environment Options

Flag Description
--kalshi-demo Use Kalshi demo environment instead of production

When --kalshi-demo is set, the engine uses: - Demo API: https://demo-api.kalshi.co - Demo WebSocket: wss://demo-api.kalshi.co/trade-api/v2/ws - Credentials from KALSHI_DEMO_KEY_ID and KALSHI_DEMO_PRIVATE_KEY

Backtesting Options

Flag Type Default Description
--from date required Start date (e.g., 2026-01-01)
--to date required End date (e.g., 2026-01-21)
--market string all Filter to specific market ID
--data-file path data/market_history.db SQLite database path
--speed float 1.0 Replay speed multiplier

Data Recording Options

Flag Type Default Description
--output path data/market_history.db Output database path

General Options

Flag Description
-h, --help Print help information
-V, --version Print version information
-v, --verbose Enable verbose logging

Modes

Normal Mode (Production)

cargo run --manifest-path arbiter-engine/Cargo.toml --release

Starts the full trading engine:

  1. Initializes exchange clients
  2. Spawns actor system (ExecutionActor, ArbiterActor, Monitors)
  3. Connects to exchange WebSockets
  4. Runs arbitrage detection loop
  5. Executes detected opportunities

Exit: Press Ctrl+C for graceful shutdown.

Dry-Run Mode

cargo run --manifest-path arbiter-engine/Cargo.toml -- --dry-run

Runs the full engine without submitting real orders:

  • All cryptographic signing executes normally
  • Order payloads printed to stdout
  • No simulated fills or position tracking
  • Safe for testing production configuration

See ADR-002 for details.

Paper Trading Mode

# Basic fidelity (instant mid-price fills)
cargo run --manifest-path arbiter-engine/Cargo.toml -- --paper-trade

# Realistic fidelity (order book crossing)
cargo run --manifest-path arbiter-engine/Cargo.toml -- --paper-trade --fidelity realistic

# With simulated latency
cargo run --manifest-path arbiter-engine/Cargo.toml -- --paper-trade --latency 50ms

Simulates order execution with position tracking:

  • Uses SimulatedExchangeClient implementing ExchangeClient trait
  • Tracks paper positions with realized/unrealized PnL
  • Calculates fees (Kalshi 7% formula, Polymarket 0%)
  • No real orders submitted

See Paper Trading Guide and ADR-014.

Backtesting Mode

# Basic backtest
cargo run --manifest-path arbiter-engine/Cargo.toml -- \
  --backtest --from 2026-01-01 --to 2026-01-21

# Specific market at 10x speed
cargo run --manifest-path arbiter-engine/Cargo.toml -- \
  --backtest --from 2026-01-01 --to 2026-01-21 \
  --market "BTC-50K-2026" --speed 10

Replays historical market data:

  • Deterministic replay (same data = same results)
  • Clock advances with each event
  • Full position tracking and PnL calculation
  • Performance metrics (Sharpe, drawdown, win rate)

See Backtesting Guide and ADR-014.

Data Recording Mode

cargo run --manifest-path arbiter-engine/Cargo.toml -- \
  --record-data --output data/market_history.db

Records live market data for later backtesting:

  • Stores orderbook snapshots to SQLite
  • Records trades and market data
  • Indexed by timestamp and market ID

Connectivity Check

cargo run --manifest-path arbiter-engine/Cargo.toml -- --check-connectivity

Verifies connectivity to exchanges:

  1. Loads credentials from environment
  2. Tests Polymarket CLOB API (/time endpoint)
  3. Tests Kalshi Trading API (/v2/exchange/status)
  4. Prints results and exits

See ADR-001 for details.

Exit Codes

Code Meaning
0 Success
1 Error (connectivity failure, configuration error, etc.)

Environment Variables

See Environment Variables Reference for full list.

Key variables for simulation:

Variable Description
ARBITER_PAPER_TRADE Enable paper trading (true/false)
ARBITER_FIDELITY Fill fidelity (basic/realistic)
ARBITER_LATENCY_MS Simulated latency in milliseconds
RUST_LOG Logging level (info, debug, trace)

Examples

# Check if credentials are valid
cargo run --manifest-path arbiter-engine/Cargo.toml -- --check-connectivity

# Test signing without submitting orders
cargo run --manifest-path arbiter-engine/Cargo.toml -- --dry-run

# Paper trade with realistic fills and 50ms latency
cargo run --manifest-path arbiter-engine/Cargo.toml -- \
  --paper-trade --fidelity realistic --latency 50ms

# Record market data
cargo run --manifest-path arbiter-engine/Cargo.toml -- \
  --record-data --output data/jan2026.db

# Backtest January 2026
cargo run --manifest-path arbiter-engine/Cargo.toml -- \
  --backtest --from 2026-01-01 --to 2026-01-31 \
  --data-file data/jan2026.db

# Run in production
cargo run --manifest-path arbiter-engine/Cargo.toml --release

# Verbose logging
RUST_LOG=debug cargo run --manifest-path arbiter-engine/Cargo.toml -- --paper-trade

Mode Comparison

Feature Normal Dry Run Paper Trade Backtest
Signs orders Yes Yes No No
Submits orders Yes No No No
Simulates fills No No Yes Yes
Tracks positions Yes No Yes Yes
Real market data Yes Yes Yes No (historical)
PnL calculation Yes No Yes Yes
Performance metrics No No Yes Yes