---
title: "CLI"
description: "Trade prediction markets, discover opportunities, and manage funds from the command line."
icon: "/images/integrations/cli.svg"
---

The Horizon CLI gives you full access to the trading engine, market discovery, wallet analytics, and fund management from your terminal. Every command supports `--json` for pipeable output.

## Installation

<CodeGroup>

```bash pip
pip install horizon-sdk
```

```bash uv
uv pip install horizon-sdk
```

```bash uvx (no install)
uvx horizon-sdk discover "election"
```

```bash bunx (no install)
bunx horizon-sdk discover "election"
```

</CodeGroup>

After installation, the `horizon` command is available on your PATH:

```bash
horizon --help
```

Or run without installing using `uvx` or `bunx`:

```bash
uvx horizon-sdk top-markets --json | jq '.[0]'
bunx horizon-sdk top-markets --json | jq '.[0]'
```

## Quick Start

```bash
# Search for markets
horizon discover "bitcoin"

# See the hottest markets
horizon top-markets --limit 5

# Size a position with Kelly
horizon kelly --prob 0.65 --price 0.50 --bankroll 1000

# Check a wallet's P&L
horizon wallet value 0x1234...abcd

# Run a strategy
horizon run my_strategy.py --mode paper --dashboard
```

## Configuration

The CLI reads configuration from environment variables:

```bash
export HORIZON_API_KEY="your-key"
export HORIZON_EXCHANGE="paper"          # paper, polymarket, kalshi
export HORIZON_DB="./horizon.db"         # persistence database path

# For Polymarket live trading
export POLYMARKET_API_KEY="..."
export POLYMARKET_API_SECRET="..."
export POLYMARKET_API_PASSPHRASE="..."
export POLYMARKET_PRIVATE_KEY="..."

# For Kalshi live trading
export KALSHI_API_KEY="..."
```

## Global Options

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON (pipeable to jq, scripts) |
| `--version` | Show version |
| `--help` | Show help |

```bash
# Human-readable output
horizon discover "election"

# JSON output for scripting
horizon discover "election" --json | jq '.[].slug'
```

## Commands

### Discovery

<AccordionGroup>

<Accordion title="discover - Search markets">

```bash
horizon discover [QUERY] [OPTIONS]
```

| Option | Default | Description |
|--------|---------|-------------|
| `--exchange` | `polymarket` | Exchange to search |
| `--limit` | `10` | Number of results |
| `--type` | `all` | `all`, `binary`, or `multi` |
| `--category` | - | Category filter (crypto, politics) |

```bash
horizon discover "election" --limit 5
horizon discover "bitcoin" --exchange kalshi
horizon discover --type binary --category crypto --json
```

</Accordion>

<Accordion title="events - Multi-outcome events">

```bash
horizon events [QUERY] [OPTIONS]
```

| Option | Default | Description |
|--------|---------|-------------|
| `--limit` | `10` | Number of events |

```bash
horizon events "super bowl" --limit 5
```

</Accordion>

<Accordion title="top-markets - Highest volume">

```bash
horizon top-markets [OPTIONS]
```

| Option | Default | Description |
|--------|---------|-------------|
| `--exchange` | `polymarket` | Exchange |
| `--limit` | `10` | Number of markets |
| `--category` | - | Category filter |

```bash
horizon top-markets --limit 20
horizon top-markets --exchange kalshi --json
```

</Accordion>

<Accordion title="market - Market detail">

```bash
horizon market SLUG [OPTIONS]
```

| Option | Default | Description |
|--------|---------|-------------|
| `--exchange` | `polymarket` | Exchange |

```bash
horizon market "will-trump-win-2024"
horizon market "KXBTC-25MAR14" --exchange kalshi --json
```

</Accordion>

</AccordionGroup>

### Trading

<AccordionGroup>

<Accordion title="submit - Place an order">

```bash
horizon submit [OPTIONS]
```

| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `--market-id` | Yes | - | Market identifier |
| `--side` | Yes | - | `buy` or `sell` |
| `--price` | Yes | - | Limit price (0-1) |
| `--size` | Yes | - | Order size |
| `--market-side` | No | `yes` | `yes` or `no` |

```bash
horizon submit --market-id will-btc-hit-100k --side buy --price 0.55 --size 10
horizon submit --market-id will-btc-hit-100k --side sell --market-side no --price 0.45 --size 5
```

</Accordion>

<Accordion title="cancel / cancel-all - Cancel orders">

```bash
horizon cancel ORDER_ID
horizon cancel-all
```

</Accordion>

<Accordion title="positions / orders / fills - View state">

```bash
horizon positions
horizon orders --market-id will-btc-hit-100k
horizon fills --limit 50
```

</Accordion>

<Accordion title="kill-switch - Emergency stop">

```bash
horizon kill-switch on --reason "volatility spike"
horizon kill-switch off
```

</Accordion>

<Accordion title="status - Engine overview">

```bash
horizon status
horizon status --json
```

Shows PnL, open orders, active positions, kill switch state, and uptime.

</Accordion>

</AccordionGroup>

### Analytics

<AccordionGroup>

<Accordion title="kelly - Position sizing">

```bash
horizon kelly [OPTIONS]
```

| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `--prob` | Yes | - | True probability (0-1) |
| `--price` | Yes | - | Market price (0-1) |
| `--bankroll` | No | `1000` | Capital in USD |
| `--fraction` | No | `0.25` | Kelly fraction |
| `--max-size` | No | `100` | Max position |

```bash
horizon kelly --prob 0.65 --price 0.50 --bankroll 5000
horizon kelly --prob 0.8 --price 0.60 --fraction 0.5 --json
```

</Accordion>

<Accordion title="parity - Arbitrage check">

```bash
horizon parity MARKET_ID [--feed FEED_NAME]
```

Checks if YES + NO prices sum to ~1.0.

```bash
horizon parity "will-btc-hit-100k"
```

</Accordion>

<Accordion title="simulate - Monte Carlo">

```bash
horizon simulate [OPTIONS]
```

| Option | Default | Description |
|--------|---------|-------------|
| `--scenarios` | `10000` | Number of paths |
| `--seed` | - | Random seed |

```bash
horizon simulate --scenarios 50000 --json
```

</Accordion>

</AccordionGroup>

### Wallet Analytics

All wallet commands are under the `wallet` subgroup:

```bash
horizon wallet COMMAND [ARGS]
```

<AccordionGroup>

<Accordion title="wallet trades - Trade history">

```bash
horizon wallet trades ADDRESS [--limit N] [--condition-id ID]
```

```bash
horizon wallet trades 0x1234...abcd --limit 20
horizon wallet trades 0x1234...abcd --json | jq '[.[] | .usdc_size] | add'
```

</Accordion>

<Accordion title="wallet positions - Open positions">

```bash
horizon wallet positions ADDRESS
```

</Accordion>

<Accordion title="wallet value - Portfolio value">

```bash
horizon wallet value ADDRESS
```

</Accordion>

<Accordion title="wallet profile - Public profile">

```bash
horizon wallet profile ADDRESS
```

</Accordion>

<Accordion title="wallet score - Performance score">

```bash
horizon wallet score ADDRESS [--limit N]
```

</Accordion>

<Accordion title="wallet top-holders - Largest holders">

```bash
horizon wallet top-holders CONDITION_ID [--limit N]
```

</Accordion>

<Accordion title="wallet flow - Buy/sell flow">

```bash
horizon wallet flow CONDITION_ID [--window HOURS] [--min-size USD]
```

</Accordion>

<Accordion title="wallet market-trades - Market trades">

```bash
horizon wallet market-trades CONDITION_ID [--limit N]
```

</Accordion>

</AccordionGroup>

### Feed Management

All feed commands are under the `feed` subgroup:

```bash
horizon feed COMMAND [ARGS]
```

<AccordionGroup>

<Accordion title="feed list - Active feeds">

```bash
horizon feed list
horizon feed list --json
```

</Accordion>

<Accordion title="feed snapshot - Latest data">

```bash
horizon feed snapshot FEED_NAME
```

</Accordion>

<Accordion title="feed health - Staleness check">

```bash
horizon feed health [--threshold SECONDS]
```

</Accordion>

<Accordion title="feed metrics - Connection stats">

```bash
horizon feed metrics FEED_NAME
```

</Accordion>

<Accordion title="feed start - Start a feed">

```bash
horizon feed start NAME TYPE [OPTIONS]
```

| Option | Description |
|--------|-------------|
| `--symbol` | Symbol for Binance feeds |
| `--url` | URL for REST feeds |
| `--config` | JSON config string |
| `--interval` | Poll interval (seconds) |

```bash
horizon feed start btc-price binance_ws --symbol btcusdt
horizon feed start nba-scores espn --config '{"sport":"basketball","league":"nba"}'
```

</Accordion>

</AccordionGroup>

### Fund Management

All fund commands are under the `fund` subgroup:

```bash
horizon fund COMMAND [ARGS]
```

<AccordionGroup>

<Accordion title="fund status / report">

```bash
horizon fund status
horizon fund report --json
```

</Accordion>

<Accordion title="fund deploy / stop / pause / resume">

```bash
horizon fund deploy --name my-mm --markets will-btc-hit-100k --mode paper
horizon fund stop my-mm
horizon fund pause my-mm
horizon fund resume my-mm
```

</Accordion>

<Accordion title="fund list / scale">

```bash
horizon fund list
horizon fund scale my-mm --capital 10000
```

</Accordion>

<Accordion title="fund nav / risk / pnl / stress-test">

```bash
horizon fund nav --limit 30
horizon fund risk
horizon fund pnl
horizon fund stress-test
```

</Accordion>

<Accordion title="fund explain / regime / alerts">

```bash
horizon fund explain
horizon fund regime
horizon fund alerts --limit 10
```

</Accordion>

</AccordionGroup>

### Account

<AccordionGroup>

<Accordion title="setup - Create account">

```bash
horizon setup user@example.com --name "My Bot"
```

</Accordion>

<Accordion title="login - Login">

```bash
horizon login user@example.com
```

</Accordion>

<Accordion title="key-status - Check credentials">

```bash
horizon key-status
```

</Accordion>

</AccordionGroup>

### Database Queries

For offline analysis of persisted strategy data, use the `db` subgroup:

```bash
horizon db COMMAND [OPTIONS]
```

<AccordionGroup>

<Accordion title="db fills - Historical fills">

```bash
horizon db fills [--path DB] [--limit N] [--market ID]
```

```bash
horizon db fills --path ./my_strategy.db --limit 20
horizon db fills --market will-btc-hit-100k
```

</Accordion>

<Accordion title="db positions - Position snapshots">

```bash
horizon db positions [--path DB]
```

</Accordion>

<Accordion title="db orders - Order history">

```bash
horizon db orders [--path DB] [--limit N] [--open-only/--all]
```

</Accordion>

</AccordionGroup>

## Scripting with --json

Every command supports `--json` for structured output. Pipe to `jq` for powerful scripting:

```bash
# Get the slug of the top market
horizon top-markets --limit 1 --json | jq -r '.[0].slug'

# Sum a wallet's total PnL
horizon wallet positions 0x1234...abcd --json | jq '[.[].pnl] | add'

# Find markets with edge > 5%
horizon discover "crypto" --json | jq '[.[] | select(.yes_price < 0.45)]'

# Kelly size across multiple scenarios
for prob in 0.55 0.60 0.65 0.70; do
  echo "prob=$prob: $(horizon kelly --prob $prob --price 0.50 --json | jq .optimal_size)"
done
```

## Architecture

The CLI shares the same tool layer as the MCP servers. All three interfaces delegate to `horizon.tools`, which wraps the Rust engine via PyO3:

```
horizon.tools (shared business logic)
    |
    +---> horizon.cli        (Click CLI, for humans)
    +---> horizon.mcp_server (MCP server, for AI agents)
    +---> horizon.mcp_fund   (MCP fund server, for AI agents)
```

This means the CLI has feature parity with the MCP interface. Same functions, same data, different transport.
