bbdata

Baseball data CLI for querying stats, generating scouting reports, and building analytics pipelines — built for humans and AI agents.

Install

# Global (CLI usage)
npm install -g bbdata

# Local (programmatic API)
npm install bbdata

Requires Node.js 18+.

Quick Start

# Pitcher's pitch mix, velocity, spin, whiff rates
bbdata query pitcher-arsenal --player "Corbin Burnes" --format table

# Advance scouting report for a starting pitcher
bbdata report advance-sp --player "Gerrit Cole" --audience coach

# Pitch movement chart (SVG)
bbdata viz movement --player "Shohei Ohtani" -o ohtani.svg

Commands

bbdata query [template]

Query baseball data using pre-built templates. Returns structured data in your choice of format.

Key options:

| Flag | Description | |---|---| | -p, --player <name> | Player name | | --players <names> | Comma-separated names (matchups/comparisons) | | -s, --season <year> | Season year (default: current) | | -f, --format <fmt> | json (default), table, csv, markdown | | --source <src> | Force data source: savant, fangraphs, mlb-stats-api | | --no-cache | Bypass cache | | --stdin | Read pre-fetched JSON from stdin | | --data <path> | Load data from a local .json or .csv file (Savant CSV schema) |

Run bbdata query --help for the full option list.

21 templates across 5 categories:

Pitcher (8) — pitcher-arsenal, pitcher-velocity-trend, pitcher-handedness-splits, pitcher-raw-pitches, pitcher-recent-form, pitcher-by-count, pitcher-tto, pitcher-season-profile

Hitter (7) — hitter-batted-ball, hitter-vs-pitch-type, hitter-hot-cold-zones, hitter-handedness-splits, hitter-zone-grid, hitter-raw-bip, hitter-season-profile

Matchup (2) — matchup-pitcher-vs-hitter, matchup-situational

Leaderboard (2) — leaderboard-custom, leaderboard-comparison

Trend (2) — trend-rolling-average, trend-year-over-year

bbdata query hitter-batted-ball --player "Aaron Judge" --format table
bbdata query leaderboard-custom --stat ERA --min-ip 100 --top 10 --format csv

bbdata report [template]

Generate scouting reports rendered from Handlebars templates. Reports pull data from multiple query templates automatically.

Key options:

| Flag | Description | |---|---| | -p, --player <name> | Player name | | -a, --audience <role> | coach, gm, scout, analyst (default: analyst) | | -f, --format <fmt> | markdown (default), json | | --validate | Run validation checklist on the report | | --no-strict | Emit stub shell instead of exiting on missing data |

13 templates across 6 categories:

Pro Scouting — pro-pitcher-eval, pro-hitter-eval, relief-pitcher-quick

Amateur Scouting — college-pitcher-draft, college-hitter-draft, hs-prospect

Advance — advance-sp, advance-lineup

Player Development — dev-progress, post-promotion

Executive — trade-target-onepager, draft-board-card, draft-board-card-pitcher

bbdata report pro-pitcher-eval --player "Corbin Burnes"
bbdata report trade-target-onepager --player "Vladimir Guerrero Jr." --audience gm

bbdata viz [type]

Generate data visualizations as SVG.

Chart types:

| Type | Description | |---|---| | movement | Pitch movement plot (horizontal break vs vertical break) | | movement-binned | Binned density variant for compact inline use | | spray | Batted ball spray chart | | zone | 3x3 strike zone heatmap (xwOBA) | | rolling | Rolling performance trend line |

Key options: --colorblind (viridis palette), -a, --audience (coach/analyst/frontoffice/presentation), --size WxH, -o, --output <path>

bbdata viz spray --player "Aaron Judge" --audience coach
bbdata viz zone --player "Shohei Ohtani" --colorblind

Output Formats

All commands support --format:

• json (default) — Structured { data, meta } envelope. Designed for piping to AI agents and scripts.
• table — Human-readable ASCII table.
• csv — Standard CSV.
• markdown — Markdown table.

Decorative output (progress, warnings) goes to stderr. Data goes to stdout. Every format is pipe-safe.

Programmatic API

import { query, report, viz, getConfig, setConfig } from 'bbdata';

const result = await query({
  template: 'pitcher-arsenal',
  player: 'Corbin Burnes',
  season: 2025,
  format: 'json',
});

console.log(result.data);   // Array of row objects
console.log(result.meta);   // { template, source, cached, sampleSize, season, queryTimeMs }

All TypeScript types are exported — see QueryOptions, ReportOptions, VizOptions, QueryResult, ReportResult, VizResult, and more.

Data Sources

The CLI tries adapters in preference order and falls back automatically:

• Savant — Pitch-level Statcast data (Baseball Savant CSV)
• FanGraphs — Season-level aggregated stats
• MLB Stats API — Rosters, schedules, and universal fallback for player resolution

Override with --source savant (or fangraphs, mlb-stats-api). Sources can be toggled in config.

Configuration

Config lives at ~/.bbdata/config.json (validated with Zod, graceful defaults if missing or corrupted):

{
  "defaultFormat": "json",
  "defaultAudience": "analyst",
  "cache": {
    "enabled": true,
    "maxAgeDays": 30
  },
  "sources": {
    "savant": { "enabled": true },
    "fangraphs": { "enabled": true },
    "mlbStatsApi": { "enabled": true }
  }
}

Access programmatically with getConfig() / setConfig().

Caching

Query results are cached in SQLite (via sql.js/WASM — zero native dependencies). Cache keys are SHA256 hashes of source:params. Default expiration is 30 days, configurable via cache.maxAgeDays. Bypass with --no-cache.

If sql.js fails to initialize, the CLI continues without cache.

Changelog

See CHANGELOG.md.

License

MIT