---
title: "Horizon CLI"
description: "Run Horizon strategies and query databases from the command line."
icon: "terminal"
---

Horizon provides a CLI for running strategies with option overrides and querying the persistence database.

## Running Strategies

```bash
python -m horizon run <strategy_file> [OPTIONS]
```

### Options

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--mode` | `paper`, `live` | from strategy | Override trading mode |
| `--dashboard / --no-dashboard` | - | from strategy | Override dashboard setting |
| `--log-level` | `debug`, `info`, `warn`, `error` | `info` | Log level for Python + Rust |

CLI options always take priority over the strategy file's `hz.run()` arguments.

### Examples

<CodeGroup>
```bash Paper with dashboard
python -m horizon run examples/simple.py --dashboard
```

```bash Live with debug logging
python -m horizon run examples/polymarket_mm.py --mode=live --log-level=debug
```

```bash Override dashboard off
python -m horizon run examples/kalshi_mm.py --no-dashboard --log-level=warn
```
</CodeGroup>

## Database Commands

### fills - Show recent fills

```bash
python -m horizon fills [OPTIONS]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--db` | `HORIZON_DB` or `./horizon.db` | Database path |
| `--limit` | `50` | Number of records |
| `--market` | all | Filter by market ID |

```bash
# Show last 50 fills
python -m horizon fills --db ./my_strategy.db

# Show fills for a specific market
python -m horizon fills --db ./my_strategy.db --market will-btc-hit-100k --limit 20
```

Output:

```
Fills (20 of 1234 total):

Time                 Market                 Side  Action    Price     Size      Fee
--------------------------------------------------------------------------------
2025-02-16 10:30:00  will-btc-hit-100k      yes   buy     0.5500     10.0   0.0055
2025-02-16 10:29:45  will-btc-hit-100k      yes   sell    0.5600      5.0   0.0028
```

### positions - Show latest snapshot

```bash
python -m horizon positions [OPTIONS]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--db` | `HORIZON_DB` or `./horizon.db` | Database path |

```bash
python -m horizon positions --db ./my_strategy.db
```

Output:

```
Position snapshot from 2025-02-16 10:30:00:

Market                 Side    Size   AvgPrice   Realized Unrealized      Total
--------------------------------------------------------------------------------
will-btc-hit-100k      yes     10.0     0.5500      $1.23     -$0.45      $0.78
KXBTC-25FEB16          no       5.0     0.4000      $0.00      $0.10      $0.10
--------------------------------------------------------------------------------
TOTAL                                               $1.23     -$0.35      $0.88
```

### orders - Show orders

```bash
python -m horizon orders [OPTIONS]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--db` | `HORIZON_DB` or `./horizon.db` | Database path |
| `--limit` | `50` | Number of records |
| `--open-only / --all` | `--open-only` | Filter by status |

```bash
# Show open orders only
python -m horizon orders --db ./my_strategy.db

# Show all orders including filled/canceled
python -m horizon orders --db ./my_strategy.db --all
```

## How CLI Overrides Work

The CLI sets overrides in the `_cli_overrides` dictionary before loading the strategy module:

1. CLI parses `--mode` and `--dashboard` flags
2. Overrides are stored in `horizon.strategy._cli_overrides`
3. The strategy file is loaded and executed
4. When `hz.run()` is called, it reads `_cli_overrides` and applies them

This means `hz.run()` in the strategy file always runs. The CLI just changes its arguments.
