CLI
The command line reaches everything the Python API reaches, and the commands mirror it: dataloader selects, downloads
and extracts the data, and evaluation backtests, fits and bets with a model on it. A command is told what to do in its
own arguments, so there is no configuration file to write first. --stats and --odds say where the data comes from,
and a source that needs a key reads it from the environment, so the key never enters a command. A model of your own is
Python, so you build it and name it: --model models.py:BETTOR.
dataloader train extract downloads the seasons once and saves the dataloader to a file. The evaluation commands read
that file with --dataloader, so the data is downloaded once and the model is trained once.
# Download once and save the dataloader
sportsbet dataloader train extract --stats football-data --odds football-data \
--league Italy --division 1 --year 2024 --odds-type market_maximum -o italy.pkl
# Backtest a model on the saved data
sportsbet evaluation backtest --dataloader italy.pkl --model logistic --betting-market draw --cv 4
# Fit the model once and save it
sportsbet evaluation fit --dataloader italy.pkl --model logistic --betting-market draw -o model.pkl
# Value bets for the upcoming matches, through the fitted model
sportsbet evaluation bet --dataloader italy.pkl --bettor model.pkl
Before a param grid exists, dataloader params shows what a source publishes and dataloader odds-types shows the odds
a selection carries. The full command reference below is generated from the tool itself, so it never falls out of date.
sportsbet
Create, test and use sports betting models.
The commands mirror the Python API. dataloader selects, downloads and extracts the data, evaluation backtests,
fits and bets with a model on it, and execution places those bets at a venue.
Usage:
sportsbet [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
dataloader
Select, download and extract data.
params and odds-types show what a source publishes. train extract downloads the seasons and saves the
dataloader, and fixtures extract downloads the upcoming matches of a saved dataloader.
Usage:
sportsbet dataloader [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
exploration
Work with the features on their own.
Usage:
sportsbet dataloader exploration [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
extract
Download the features of the selection.
Usage:
sportsbet dataloader exploration extract [OPTIONS]
Options:
--league TEXT A league to select. Repeat it to select
more.
--division INTEGER A division to select. Repeatable.
--year INTEGER A season, by the year it ends. Repeatable.
--stats [euroleague|football-data|nba]
Where the statistics come from. [required]
--odds [football-data|odds-api]
Where the odds come from.
--odds-key-env TEXT The environment variable holding the odds
key. [default: ODDS_API_KEY]
--odds-market TEXT A market to price, e.g. `h2h`. Repeatable.
--odds-region TEXT A region to price, e.g. `eu`. Repeatable.
--odds-moment TEXT A moment to price, as `status:minutes`, e.g.
`inplay:45`. Repeatable.
--alias TEXT A team the sources spell differently, as
`stats name=odds name`. Repeatable.
--drop-na-thres FLOAT The threshold to drop missing columns.
[default: 0.0]
--target-event-status [preplay|inplay|postplay]
Where the targets are taken from.
--target-event-time TEXT The moment of the targets when they are in-
play, e.g. `45min`.
--input-event-status [preplay|inplay|postplay]
The latest snapshot kept as a feature. The
default keeps every one before the target.
--input-event-time TEXT The moment of the input horizon, e.g.
`45min`.
-o, --output PATH A directory to write the results to, as CSV.
--help Show this message and exit.
fixtures
Work with the upcoming matches a model bets on.
Usage:
sportsbet dataloader fixtures [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
extract
Download the upcoming matches of a saved dataloader.
Usage:
sportsbet dataloader fixtures extract [OPTIONS]
Options:
-d, --dataloader PATH A dataloader saved by `dataloader train extract`.
[required]
-o, --output PATH A directory to write the results to, as CSV.
--help Show this message and exit.
odds-types
Show the odds types a selection carries.
Downloads the data to read them.
Usage:
sportsbet dataloader odds-types [OPTIONS]
Options:
--league TEXT A league to select. Repeat it to select
more.
--division INTEGER A division to select. Repeatable.
--year INTEGER A season, by the year it ends. Repeatable.
--stats [euroleague|football-data|nba]
Where the statistics come from. [required]
--odds [football-data|odds-api]
Where the odds come from.
--odds-key-env TEXT The environment variable holding the odds
key. [default: ODDS_API_KEY]
--odds-market TEXT A market to price, e.g. `h2h`. Repeatable.
--odds-region TEXT A region to price, e.g. `eu`. Repeatable.
--odds-moment TEXT A moment to price, as `status:minutes`, e.g.
`inplay:45`. Repeatable.
--alias TEXT A team the sources spell differently, as
`stats name=odds name`. Repeatable.
--help Show this message and exit.
params
Show the leagues, divisions and seasons a source publishes.
Usage:
sportsbet dataloader params [OPTIONS]
Options:
--league TEXT A league to select. Repeat it to select
more.
--division INTEGER A division to select. Repeatable.
--year INTEGER A season, by the year it ends. Repeatable.
--stats [euroleague|football-data|nba]
Where the statistics come from. [required]
--odds [football-data|odds-api]
Where the odds come from.
--odds-key-env TEXT The environment variable holding the odds
key. [default: ODDS_API_KEY]
--odds-market TEXT A market to price, e.g. `h2h`. Repeatable.
--odds-region TEXT A region to price, e.g. `eu`. Repeatable.
--odds-moment TEXT A moment to price, as `status:minutes`, e.g.
`inplay:45`. Repeatable.
--alias TEXT A team the sources spell differently, as
`stats name=odds name`. Repeatable.
--help Show this message and exit.
train
Work with the training data a model learns from.
Usage:
sportsbet dataloader train [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
extract
Download the training data and save the dataloader to a file.
Usage:
sportsbet dataloader train extract [OPTIONS]
Options:
--league TEXT A league to select. Repeat it to select
more.
--division INTEGER A division to select. Repeatable.
--year INTEGER A season, by the year it ends. Repeatable.
--stats [euroleague|football-data|nba]
Where the statistics come from. [required]
--odds [football-data|odds-api]
Where the odds come from.
--odds-key-env TEXT The environment variable holding the odds
key. [default: ODDS_API_KEY]
--odds-market TEXT A market to price, e.g. `h2h`. Repeatable.
--odds-region TEXT A region to price, e.g. `eu`. Repeatable.
--odds-moment TEXT A moment to price, as `status:minutes`, e.g.
`inplay:45`. Repeatable.
--alias TEXT A team the sources spell differently, as
`stats name=odds name`. Repeatable.
--odds-type TEXT The odds to extract, e.g. `market_average`.
--drop-na-thres FLOAT The threshold to drop missing columns.
[default: 0.0]
--target-event-status [preplay|inplay|postplay]
Where the targets are taken from.
--target-event-time TEXT The moment of the targets when they are in-
play, e.g. `45min`.
--input-event-status [preplay|inplay|postplay]
The latest snapshot kept as a feature. The
default keeps every one before the target.
--input-event-time TEXT The moment of the input horizon, e.g.
`45min`.
-o, --output PATH Where to save the dataloader. [required]
--help Show this message and exit.
evaluation
Backtest, fit and bet with a model on a saved dataloader.
Usage:
sportsbet evaluation [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
backtest
Backtest a model on a saved dataloader's training data.
Usage:
sportsbet evaluation backtest [OPTIONS]
Options:
-d, --dataloader PATH A dataloader saved by `dataloader train extract`.
[required]
--model TEXT A scikit-learn estimator as a Python expression, as
in `"OddsComparisonBettor(alpha=0.05)"` or
`"ClassifierBettor(LogisticRegression(C=1.0))"`, or
one you built, named by where it lives, as in
`models.py:BETTOR`.
--cv INTEGER The number of time-ordered folds. [default: 3]
--n-jobs INTEGER The jobs the backtest runs in parallel. [default:
-1]
--verbose INTEGER How much the backtest says while it runs. [default:
0]
-o, --output PATH A directory to write the results to, as CSV.
--help Show this message and exit.
bet
Predict the value bets of the upcoming matches with a model saved by fit.
Usage:
sportsbet evaluation bet [OPTIONS]
Options:
-d, --dataloader PATH A dataloader saved by `dataloader train extract`.
[required]
-b, --bettor PATH A model saved by `fit`. [required]
-o, --output PATH A directory to write the bets to, as CSV.
--help Show this message and exit.
fit
Fit a model on a saved dataloader's training data and save it.
Usage:
sportsbet evaluation fit [OPTIONS]
Options:
-d, --dataloader PATH A dataloader saved by `dataloader train extract`.
[required]
--model TEXT A scikit-learn estimator as a Python expression, as
in `"OddsComparisonBettor(alpha=0.05)"` or
`"ClassifierBettor(LogisticRegression(C=1.0))"`, or
one you built, named by where it lives, as in
`models.py:BETTOR`.
-o, --output PATH Where to save the fitted model. [required]
--help Show this message and exit.
execution
Place the value bets a model found, at a venue where you hold an account.
Read the execution page of the user guide before using any of this: it spends real money.
Usage:
sportsbet execution [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
balance
Show the balance and what is currently at stake.
Usage:
sportsbet execution balance [OPTIONS]
Options:
--venue TEXT Your venue, as `venue.py:VENUE`. [required]
--help Show this message and exit.
cancel
Cancel a bet, where the venue cancels.
Usage:
sportsbet execution cancel [OPTIONS]
Options:
--venue TEXT Your venue, as `venue.py:VENUE`. [required]
--match TEXT The match the bet is on. [required]
--market TEXT The market the bet is on. [required]
--selection TEXT The selection the bet backs. [required]
--help Show this message and exit.
markets
Show the markets a venue offers on the upcoming matches, with their prices.
Usage:
sportsbet execution markets [OPTIONS]
Options:
--venue TEXT Your venue, as `venue.py:VENUE`. [required]
-d, --dataloader PATH A saved dataloader. [required]
--help Show this message and exit.
page
Read and act on a bookmaker's website.
Each command is a whole session: it opens the browser, goes to the page, does the one thing and closes. A ref comes
from the snapshot of the page it was read on, so pass the same --url that produced it.
Driving a bookmaker's website breaches essentially every bookmaker's terms of service and risks the account being closed and the balance lost. The library supplies the browser and the page, and the knowledge of the site is yours.
Usage:
sportsbet execution page [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
act
Act on a page and show what the action produced.
Usage:
sportsbet execution page act [OPTIONS]
Options:
--venue TEXT Your venue, as `venue.py:VENUE`. [required]
--url TEXT The page the ref was read on. [required]
--click TEXT The ref of an element to click.
--type TEXT The ref of an element to fill.
--text TEXT What to fill it with.
--select TEXT The ref of an element to choose an option in.
--value TEXT The option to choose.
--help Show this message and exit.
fix
Pin what exploring found.
Usage:
sportsbet execution page fix [OPTIONS]
Options:
--venue TEXT Your venue, as `venue.py:VENUE`. [required]
--url TEXT The page that was explored. [required]
--match TEXT The match to pin the session to. [required]
--locator TEXT Something found, as `name=locator`, e.g.
`stake=textbox[name="Stake"]`. Repeatable.
--help Show this message and exit.
read
Show a page an agent can act on.
Usage:
sportsbet execution page read [OPTIONS]
Options:
--venue TEXT Your venue, as `venue.py:VENUE`. [required]
--url TEXT The page to read. Without it the venue's own url is read.
--selector TEXT The part of the page to read. Reading a part keeps a turn
cheap.
--depth INTEGER How far down to read.
--help Show this message and exit.
run
Watch one event and place the model's bet at its moment.
It explores the URLs to match the event, prompts the login, logs the event to the terminal, and at the fitted moment
places the stake on the model's selection. Without --live it stakes nothing and logs the bet it would have made.
Usage:
sportsbet execution run [OPTIONS]
Options:
--venue TEXT Your browser session, as `venue.py:VENUE`.
[required]
-d, --dataloader PATH A saved dataloader configured for the event.
[required]
-b, --bettor PATH A model saved by `fit`. [required]
--event TEXT The one event to act on, as `Home vs Away`.
[required]
--stake FLOAT The fixed stake to place. [required]
--url TEXT A candidate bookmaker URL. Repeatable.
--live Arm the run. Off by default, which is a dry run.
--poll TEXT The source poll interval, as `30s` or `2min`.
-o, --output PATH A directory to write the receipt CSV to.
--help Show this message and exit.
status
Show what the venue holds for one bet.
Usage:
sportsbet execution status [OPTIONS]
Options:
--venue TEXT Your venue, as `venue.py:VENUE`. [required]
--match TEXT The match the bet is on. [required]
--market TEXT The market the bet is on. [required]
--selection TEXT The selection the bet backs. [required]
--help Show this message and exit.
venue
Show what a venue is and what it was told about the site.
Usage:
sportsbet execution venue [OPTIONS]
Options:
--venue TEXT Your venue, as `venue.py:VENUE`. [required]
--help Show this message and exit.