Scottfree Sports CLI #

sfs is the command-line interface for Scottfree Sports. It lets Premium subscribers query model predictions, current odds, historical results, summaries, account usage, public consensus, weather, live scores, rosters, injuries, and prediction-market context from a terminal.

The MCP server (sfs-mcp) ships in the same package. See MCP Server Setup for assistant workflows.

Access #

The CLI uses the same Scottfree Sports API key as the web app and REST API.

Install #

Requires Python 3.11 or newer.

python3 --version
python3 -m pip install --upgrade scottfree-sports-cli

Verify:

sfs --version
sfs --help

Configure #

Production profile:

sfs config set \
  --api-key sk_alphapysports_PASTE_YOUR_KEY \
  --api-url https://sports-api.scottfreellc.com \
  --env default

Store keys in macOS Keychain or your system keyring:

sfs config set --api-key sk_alphapysports_PASTE_YOUR_KEY --use-keyring

Show the current profile:

sfs config show

List profiles:

sfs config profiles

Config file location:

~/.sfs/config.toml

Resolution order:

1. SFS_API_KEY and SFS_API_URL environment variables.
2. System keyring value if the profile stores keyring:.
3. The selected profile in ~/.sfs/config.toml.
4. Default API URL: https://sports-api.scottfreellc.com.

Sports And Model Types #

Sports:

mlb, nba, nfl, nhl, ncaaf, ncaab

Model type shorthands:

List from the API:

sfs predictions list-sports

Command Map #

Daily Brief #

The brief combines over/under and spread model data for the slate. It returns:

• game date and ET game time,
• teams,
• current line,
• ML model pick label,
• model probability,
• market-implied probability,
• signed Delta(Model-Implied) in percentage points,
• count of individual models above or below market-implied probability.

sfs brief get mlb
sfs brief get nhl --output json
sfs brief get nba -o json

Output modes:

Important reading rules:

• Spread is home-relative.
• Moneyline is home-relative.
• Over/under is over-relative.
• Delta(Model-Implied) is model probability minus market-implied probability on that axis.
• The brief is model research, not a guaranteed betting recommendation.

Predictions #

sfs predictions get mlb moneyline
sfs predictions get mlb ml
sfs predictions get nba spread
sfs predictions get nhl over_under
sfs predictions get mlb ou --output json
sfs predictions get mlb spread -o csv
sfs predictions get mlb moneyline --no-color

Output modes:

Prediction output includes the model probability columns:

IMPLIED, AI, BLEND, CATB, RF, LGB, LOGR, XGB, XT

The JSON response also includes line fields such as:

open_over_under, over_under,
open_home_point_spread, home_point_spread,
open_home_money_line, home_money_line,
open_away_money_line, away_money_line

Results #

sfs results get mlb moneyline
sfs results get nba spread --limit 25
sfs results get nhl over_under -l 50

Current CLI behavior: results render as a Rich table. Use the REST API directly for full JSON:

curl -H "X-API-Key: $SFS_API_KEY" \
  "https://sports-api.scottfreellc.com/api/v1/results/mlb/won_on_points?limit=25"

Summary #

sfs summary get mlb moneyline
sfs summary get nba spread
sfs summary get nhl over_under

Current CLI behavior: summary renders as a Rich table. Use the REST API directly for full JSON:

curl -H "X-API-Key: $SFS_API_KEY" \
  https://sports-api.scottfreellc.com/api/v1/summary/mlb/won_on_points

Odds #

sfs odds get mlb
sfs odds get nba

Current CLI behavior: odds render as a Rich table. Use the REST API directly for full JSON:

curl -H "X-API-Key: $SFS_API_KEY" \
  https://sports-api.scottfreellc.com/api/v1/odds/mlb

Consensus #

Public betting consensus comes from Covers.

sfs consensus get mlb
sfs consensus get nba -o json
sfs consensus get nfl -o csv

Output modes:

table, json, csv

Weather #

Weather covers outdoor venue sports where venue mapping is available.

sfs weather get mlb
sfs weather get nfl -o json
sfs weather get ncaaf -o csv

Output modes:

table, json, csv

Live Scores, Injuries, And Players #

These commands use BALLDONTLIE. Configure your own BALLDONTLIE key:

sfs config set --balldontlie-api-key YOUR_BALLDONTLIE_KEY --use-keyring

Scores:

sfs scores scores nba
sfs scores scores mlb --date 2026-05-23
sfs scores scores nhl -o json

Injuries:

sfs scores injuries nba
sfs scores injuries nfl -o json

BALLDONTLIE player injuries require their GOAT tier. Lower tiers return a clear upgrade-required message.

Players:

sfs scores players nba
sfs scores players nba --search James
sfs scores players nba --team-id 14 --per-page 50
sfs scores players mlb -o csv

Output modes:

table, json, csv

Prediction Markets #

Kalshi:

sfs markets kalshi nfl
sfs markets kalshi nba -o json

Polymarket:

sfs markets polymarket mlb
sfs markets polymarket nba -o csv

Compare model predictions with market data:

sfs markets compare mlb
sfs markets compare nba -o json

Output modes:

table, json, csv

Account #

Account info:

sfs account info
sfs account info -o json

Usage:

sfs account usage
sfs account usage -o json

Keys:

sfs account keys
sfs account keys -o json
sfs account create-key --name "Research Laptop"
sfs account rename-key sk_alphapysports_abcd***** --name "Production App"
sfs account revoke-key sk_alphapysports_abcd*****

The API will not let you revoke the key currently being used for the request.

Environment Variables #

Shell Completion #

Typer can install shell completions:

sfs --install-completion

Print completion script:

sfs --show-completion

Troubleshooting #

No API key configured #

Run:

sfs config set --api-key sk_alphapysports_PASTE_YOUR_KEY

or set:

export SFS_API_KEY="sk_alphapysports_PASTE_YOUR_KEY"

401 Invalid or expired API key #

Check the key in the Account page, then update the CLI profile. If you regenerated or revoked a key, old CLI profiles still point at the old key until changed.

403 #

Your key is valid but your product does not allow that command. CLI access is Premium only.

BALLDONTLIE errors #

Scores and players need a BALLDONTLIE key. Injuries require BALLDONTLIE GOAT tier.

Need raw JSON for a table-only command #

Use the REST API directly with curl. The CLI intentionally keeps results, summary, and odds as terminal tables today.

For copyable command examples grouped by task, see CLI Examples.