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

Market Discovery Options¶

Feature Flag Required

Market discovery commands require the discovery feature flag:

cargo build --features discovery
cargo run --features discovery -- [OPTIONS]

Core Commands¶

Flag	Type	Default	Description
`--discover-markets`	flag	-	Trigger a market discovery scan
`--list-candidates`	flag	-	List discovery candidates
`--status`	`pending`\|`approved`\|`rejected`\|`all`	`all`	Filter candidates by status
`--discovery-db`	path	`discovery.db`	Path to discovery SQLite database

Approval Commands¶

Flag	Type	Default	Description
`--approve-candidate`	UUID	-	Approve a candidate by ID
`--acknowledge-warnings`	flag	`false`	Acknowledge semantic warnings when approving
`--reject-candidate`	UUID	-	Reject a candidate by ID
`--reason`	string	-	Reason for rejection (required with `--reject-candidate`)

Debug Commands (Phase 2-5)¶

Flag	Type	Default	Description
`--show-fingerprint`	flag	-	Display fingerprint for a market
`--ticker`	string	-	Market ticker for fingerprint display
`--test-match`	flag	-	Test matching between two markets
`--kalshi`	string	-	Kalshi ticker for test-match
`--poly`	string	-	Polymarket condition ID for test-match
`--evaluate-matching`	flag	-	Run evaluation on golden test set
`--golden-set`	path	-	Path to golden pairs JSON file

Training & Export Commands (Phase 5)¶

Flag	Type	Default	Description
`--export-training-data`	flag	-	Export decisions as JSONL training data
`--output`	path	`training.jsonl`	Output path for training data export
`--stratified-sample`	integer	-	Sample size per category for balanced dataset

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:

Initializes exchange clients
Spawns actor system (ExecutionActor, ArbiterActor, Monitors)
Connects to exchange WebSockets
Runs arbitrage detection loop
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

Market Discovery Mode¶

# Build with discovery feature
cargo build --manifest-path arbiter-engine/Cargo.toml --features discovery

# Run discovery scan
cargo run --manifest-path arbiter-engine/Cargo.toml --features discovery -- --discover-markets

# List pending candidates
cargo run --manifest-path arbiter-engine/Cargo.toml --features discovery -- \
  --list-candidates --status pending

# Approve a candidate (no warnings)
cargo run --manifest-path arbiter-engine/Cargo.toml --features discovery -- \
  --approve-candidate 550e8400-e29b-41d4-a716-446655440000

# Approve a candidate with semantic warnings
cargo run --manifest-path arbiter-engine/Cargo.toml --features discovery -- \
  --approve-candidate 550e8400-e29b-41d4-a716-446655440000 --acknowledge-warnings

# Reject a candidate with reason
cargo run --manifest-path arbiter-engine/Cargo.toml --features discovery -- \
  --reject-candidate 550e8400-e29b-41d4-a716-446655440000 \
  --reason "Different settlement criteria"

Phase 2-5 Debug Commands¶

# Show fingerprint for a specific market
cargo run --manifest-path arbiter-engine/Cargo.toml --features discovery -- \
  --show-fingerprint --ticker "KXBTC-100K-2026"

# Test matching between two specific markets
cargo run --manifest-path arbiter-engine/Cargo.toml --features discovery -- \
  --test-match --kalshi "KXBTC-100K-2026" --poly "0x123..."

# Evaluate matching against golden test set
cargo run --manifest-path arbiter-engine/Cargo.toml --features discovery -- \
  --evaluate-matching --golden-set arbiter-engine/tests/golden_pairs.json

# Export training data for model improvement
cargo run --manifest-path arbiter-engine/Cargo.toml --features discovery -- \
  --export-training-data --output training.jsonl

# Export stratified sample (100 per category)
cargo run --manifest-path arbiter-engine/Cargo.toml --features discovery -- \
  --export-training-data --output training.jsonl --stratified-sample 100

Automates market pair discovery between Polymarket and Kalshi using a five-phase pipeline:

Phase 1 (Text): Fast filtering using Jaccard + Levenshtein similarity
Phase 2 (Fingerprint): Structured field matching (entity, date, threshold)
Phase 3 (Embedding): Semantic vector similarity
Phase 4 (LLM): AI verification for uncertain cases
Phase 5 (Learning): Continuous improvement from human decisions

Key features:

Hybrid scoring: 0.50 × fingerprint + 0.40 × embedding + 0.10 × text
Automatic alias learning from approved matches
LLM escalation for uncertain cases (0.60-0.85 score range)
Decision logging for training data export

Human-in-the-Loop Required

All discovered market pairs must be reviewed and approved by a human operator before they can be used for trading. This is a safety-critical requirement (FR-MD-003).

See Market Discovery Guide and ADR-017.

Connectivity Check¶

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

Verifies connectivity to exchanges:

Loads credentials from environment
Tests Polymarket CLOB API (/time endpoint)
Tests Kalshi Trading API (/v2/exchange/status)
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

# Market discovery workflow (requires --features discovery)
cargo run --manifest-path arbiter-engine/Cargo.toml --features discovery -- --discover-markets
cargo run --manifest-path arbiter-engine/Cargo.toml --features discovery -- --list-candidates --status pending
cargo run --manifest-path arbiter-engine/Cargo.toml --features discovery -- \
  --approve-candidate <uuid> --acknowledge-warnings

Mode Comparison¶

Feature	Normal	Dry Run	Paper Trade	Backtest	Discovery
Signs orders	Yes	Yes	No	No	No
Submits orders	Yes	No	No	No	No
Simulates fills	No	No	Yes	Yes	No
Tracks positions	Yes	No	Yes	Yes	No
Real market data	Yes	Yes	Yes	No (historical)	Yes
PnL calculation	Yes	No	Yes	Yes	No
Performance metrics	No	No	Yes	Yes	No
Human approval	N/A	N/A	N/A	N/A	Required
Feature flag	None	None	None	None	`discovery`