FBS CLI

Unofficial · 71 read-only routes + team analysis · agent-ready

The shortest path from question to kickoff data.

FBS CLI is an independent command line interface for CollegeFootballData. It covers all 71 GET routes in the pinned cfbd 5.21.0 client, plus a cutoff-safe analyze team report, and returns every result as clean YAML.

Start in three steps View and star on GitHub Open npm 
$ fbs games --year 2024 --week 1 --team "Florida State"

command: games
endpoint: /games
query:
  year: 2024
  week: 1
  team: Florida State
count: 1
games:
  - season: 2024
    week: 1
    matchup: Boston College at Florida State
    status: completed

Up and running in three steps.

Install the cross-platform npm package, configure your key, then make a focused first query.

01

Install the CLI

Use Node.js >=22.12.0 on Windows, macOS, or Linux. For occasional use, run it directly with npx @jvorndran/fbs-cli.

npm install --global @jvorndran/fbs-cli
02

Configure access

Request a free CFBD key, then run this command. It explains the validation and project-local save before asking for the key at a masked prompt.

fbs auth
03

Make a first call

Run fbs --help, start with teams or games, then reuse returned IDs for deeper queries.

fbs teams fbs --year 2026

Ask for a handicap. Get an investigation—not a hunch.

Build a team dossier, investigate the next matchup, and audit the result. Bring a timestamped sportsbook number and current availability news; FBS CLI supplies structured CFBD evidence.

  1. Team dossier Separate record, efficiency, opponent quality, personnel, and market history.
  2. Pregame betting card Test the matchup and current number with a strict pre-kickoff data cutoff.
  3. Postgame audit Separate result from process, then carry durable lessons forward.

Each audit updates the next team dossier.

Build the full team handicap file Test whether the record, underlying play, and historical market results tell the same story. Reusable dossier
Agent prompt
Investigate 2025 Florida State. Determine whether its record was supported by opponent quality, underlying efficiency, recent form, player concentration, and historical market performance. Identify the conditions that made the team attractive or dangerous for sides and totals.
Phase 01

Results and market history

Establish the schedule ledger, expected record, ATS sample, and stored provider observations.

fbs games --year 2025 --team "Florida State" --season-type regular
fbs records --year 2025 --team "Florida State"
fbs teams ats --year 2025 --team "Florida State"
fbs lines --year 2025 --team "Florida State" --season-type regular
Phase 02

Efficiency and trend splits

Contrast full-season quality with early and late form while removing garbage time.

fbs stats season advanced --year 2025 --team "Florida State" --exclude-garbage-time
fbs stats season advanced --year 2025 --team "Florida State" --start-week 1 --end-week 7 --exclude-garbage-time
fbs stats season advanced --year 2025 --team "Florida State" --start-week 8 --end-week 14 --exclude-garbage-time
fbs ppa games --year 2025 --team "Florida State" --exclude-garbage-time
fbs wepa team season --year 2025 --team "Florida State"
Phase 03

Opponent quality and ratings

Check whether schedule strength and multiple provider rating systems confirm the raw profile.

fbs ratings srs expanded --year 2025
fbs ratings sp --year 2025 --team "Florida State"
fbs ratings fpi --year 2025 --team "Florida State"
Phase 04

Personnel concentration

Find out whether production is distributed or dependent on a small number of players.

fbs player usage --year 2025 --team "Florida State" --exclude-garbage-time
fbs ppa players season --year 2025 --team "Florida State" --threshold 10 --exclude-garbage-time
Join the evidence. Match games[].id with lines[].id, then join each opponent name to the expanded SRS rows.
Keep market context descriptive. Show provider and sample size; do not treat a stored spread as a guaranteed live or closing number.
Final artifact

Reusable team betting profile

TEAM DOSSIER
Record vs. expected wins:
Opponent quality and strength of schedule:
Offensive and defensive identity:
Early vs. late trend:
Game-to-game volatility:
Player concentration:
Side-friendly conditions:
Total-friendly conditions:
Historical ATS and provider context:
Conflicting evidence and data gaps:
Produce the pregame side and total card Use only information available before kickoff, then grade both markets at the verified price. Side + total
Agent prompt
Investigate {TEAM} versus {OPPONENT} using only information available before kickoff. The live market from {SPORTSBOOK} at {TIMESTAMP} is {SPREAD_AND_PRICE} with a total of {TOTAL_AND_PRICE}. Availability notes: {NOTES}. Return one side and one total entry with a bettable number, counterarguments, invalidation conditions, and a 0u, 0.5u, or 1u grade.
Required live inputs. Supply sportsbook, timestamp, spread, total, prices, verified availability notes, and your own definition of one unit.
Pass the timing gate. Run the live card before kickoff. Confirm the target game has completed: false, the current time precedes start_date, and each cutoff is that team’s last completed week.
Phase 01

Build the schedule ledger and benchmark

Locate the target by opponent, capture its ID and week, derive each team’s completed-game weeks, then add stored market and model context.

fbs games --year {YEAR} --team "{TEAM}" --season-type regular
fbs games --year {YEAR} --team "{OPPONENT}" --season-type regular
fbs games --year {YEAR} --week {TARGET_WEEK} --team "{TEAM}" --season-type regular
fbs lines --game-id {GAME_ID}
fbs teams ats --year {YEAR} --team "{TEAM}"
fbs teams ats --year {YEAR} --team "{OPPONENT}"
fbs metrics wp pregame --year {YEAR} --week {TARGET_WEEK} --team "{TEAM}"
fbs ratings elo --year {YEAR} --week {TARGET_WEEK} --team "{TEAM}"
fbs ratings elo --year {YEAR} --week {TARGET_WEEK} --team "{OPPONENT}"
Phase 02

Map the efficiency mismatch

Repeat for both teams, then compare each offense with the opposing defense.

fbs stats season advanced --year {YEAR} --team "{TEAM}" --start-week 0 --end-week {CUTOFF_WEEK} --exclude-garbage-time
fbs stats game havoc --year {YEAR} --team "{TEAM}" --season-type regular
fbs ppa games --year {YEAR} --team "{TEAM}" --season-type regular --exclude-garbage-time
Phase 03

Stress-test volume and personnel

Repeat for both teams. Query plays once for each team’s last three completed-game weeks; byes mean those weeks can differ.

fbs drives --year {YEAR} --team "{TEAM}" --season-type regular
fbs plays --year {YEAR} --week {EACH_COMPLETED_WEEK} --team "{TEAM}" --season-type regular
fbs stats player season --year {YEAR} --team "{TEAM}" --start-week 0 --end-week {CUTOFF_WEEK} --season-type regular
fbs player usage --year {YEAR} --team "{TEAM}" --exclude-garbage-time
fbs ppa players games --year {YEAR} --team "{TEAM}" --threshold 10 --season-type regular --exclude-garbage-time
Phase 04

Add low-weight context

Use series history as context only and treat tier-denied weather as missing evidence.

fbs teams matchup --team1 "{TEAM}" --team2 "{OPPONENT}" --min-year {HISTORY_START} --max-year {PRIOR_YEAR}
fbs games weather --game-id {GAME_ID}
Side lens. Compare passing, rushing, standard downs, passing downs, line play, havoc, recent form, ratings, and player concentration.
Total lens. Test game scripts using play volume, drives, explosiveness, scoring opportunities, field position, availability, and weather.
Historical replay rule. Keep only game-level rows with week < TARGET_WEEK. Omit season ATS, player usage, WEPA, SP+, FPI, and forecast-weather claims unless archived before kickoff; use the target game’s preserved pregame_elo instead of assuming weekly Elo timing.
Count evidence families once. Treat matchup efficiency, ratings/pregame probability, volume and game script, and personnel/availability as distinct primary families. Correlated metrics within one family count once; ATS and head-to-head remain context only.
Final artifact

Always return both markets

MARKET SNAPSHOT
Sportsbook:
Captured at:
Verified spread, total, and prices:
Availability snapshot:
One-unit definition:

SIDE
Decision: PASS | LEAN | PLAY
Selection: {TEAM_AND_EXACT_VERIFIED_SPREAD}
Price:
Grade: 0u | 0.5u | 1u
Heuristic fair range:
Bettable through:
Evidence for:
Evidence against:
Valid only at:
Invalidated by:
Missing inputs:

TOTAL
Decision: PASS | LEAN | PLAY
Selection: Over/Under {EXACT_VERIFIED_TOTAL}
Price:
Grade: 0u | 0.5u | 1u
Heuristic fair range:
Bettable through:
Evidence for:
Evidence against:
Valid only at:
Invalidated by:
Missing inputs:
  • PLAY · 1u Three primary families agree, both teams have four relevant games, price and pivotal availability are verified, and no major contradiction remains.
  • LEAN · 0.5u Two primary families agree, but one noncritical uncertainty or counter-signal remains.
  • PASS · 0u Evidence is weak or split, the sample is thin, the live price is missing or moved, or availability or material weather is unresolved.

Maximum exposure is 1u per entry. Historical ATS and head-to-head never raise a tier by themselves, and units are never converted to dollars.

Run the signal-or-noise postgame audit Separate the result from the reasoning, then update the profile without outcome chasing. Feedback loop
Agent prompt
Audit game {GAME_ID} against the original betting card. Separate the betting result from the quality of the reasoning, identify high-variance events, determine whether the matchup thesis held, and update the team dossier without outcome chasing.
Phase 01

Record the result and context

Use the original timestamped sportsbook number as the authoritative grading input.

fbs games --id {GAME_ID}
fbs lines --game-id {GAME_ID}
fbs games teams --id {GAME_ID}
fbs games players --id {GAME_ID}
Phase 02

Test whether the thesis held

Compare the final score with efficiency, disruption, and predicted-points evidence.

fbs stats game advanced --year {YEAR} --week {WEEK} --team "{TEAM}" --opponent "{OPPONENT}" --exclude-garbage-time
fbs stats game havoc --year {YEAR} --week {WEEK} --team "{TEAM}" --opponent "{OPPONENT}"
fbs ppa games --year {YEAR} --week {WEEK} --team "{TEAM}" --exclude-garbage-time
Phase 03

Locate variance and turning points

Trace field position, explosive plays, short fields, and the largest win-probability swings.

fbs drives --year {YEAR} --week {WEEK} --team "{TEAM}"
fbs plays --year {YEAR} --week {WEEK} --team "{TEAM}"
fbs metrics wp --game-id {GAME_ID}
Optional

Use the consolidated advanced box

Add this evidence only when the authenticated CFBD tier permits the endpoint.

fbs game box advanced --id {GAME_ID}
Grade both recorded entries. Determine each side and total result against the sportsbook number and price captured before kickoff—not a later provider observation.
Separate process from outcome. Turnovers, special teams, short fields, explosive plays, and garbage time can overwhelm an otherwise sound thesis.
Final artifact

Postgame process audit

POSTGAME AUDIT
Sportsbook and captured-at timestamp:
Pregame availability snapshot:

SIDE AUDIT
Recorded selection, price, and grade:
Result: WIN | LOSS | PUSH
Thesis status: CONFIRMED | MIXED | REFUTED
Evidence that held / failed:

TOTAL AUDIT
Recorded selection, price, and grade:
Result: WIN | LOSS | PUSH
Thesis status: CONFIRMED | MIXED | REFUTED
Evidence that held / failed:

SHARED PROCESS REVIEW
Repeatable efficiency signals:
High-variance events:
Largest win-probability swings:
Profile upgrades / holds / downgrades:
Next-game watch conditions:
Remaining uncertainty:

One predictable surface, across every research domain.

Command families stay close to CFBD REST paths. Use built-in help for the exact flags on any of the 71 endpoint commands.

Team analysis

analyze team

Build a fresh, cutoff-safe YAML report with record, offense and defense efficiency, drives, PROE, player trends, and adjusted ranks.

Teams & reference

teams · roster · records

Discover programs, conferences, venues, talent, calendars, rosters, historical series, and ATS records.

Games & live

games · lines · live

Find schedules and IDs, then retrieve box scores, historical provider lines, media, weather, scoreboards, and live plays.

Possessions

drives · plays

Trace possessions, play-by-play, play types, and explicit athlete-to-play stat associations.

Performance

stats · player

Query team and player production, advanced efficiency, havoc, usage, transfers, and success rates.

Analytics

ppa · metrics · wepa

Explore predicted points, win probability, field-goal EP, and opponent-adjusted team or player metrics.

History & context

ratings · recruiting · more

Cover polls, ratings, recruiting, playoffs, draft history, coaches, and returning production.

Designed for reliable handoffs

One quiet, predictable YAML document.

Successful requests write only structured YAML to stdout. Errors use the same approach on stderr, with stable codes and useful hints. The structural example is abridged.

  • Snake-case keys
  • Null values removed
  • Provider IDs preserved
  • No banners, spinners, or color codes
command: games teams
endpoint: /games/teams
query:
  id: 401752731
count: 1
games:
  - game_id: 401752731
    teams:
      - team: Florida State
        home_away: home
        stats:
          total_yards: 412
          rushing_yards: 156