Querying data
Every command follows the same pattern:
restish pff <command> <required arguments> [--optional flags]- Required parameters are positional, in the order
--helplists them. - Optional parameters are
--flags. --helpon any command shows both, with the values they accept.
restish pff games --helpUsage:
restish pff ref-games <league> <season> <week> [flags]
Aliases:
ref-games, games
Argument Schema:
{
league: (string enum:nfl,ncaa,hs,aaf,ufl)
season: (integer)
week: (integer)
}
Option Schema:
{
--franchise: (integer)
}Start with the reference data
restish pff leagues # leagues, their seasons and week groups
restish pff games nfl 2025 1 # results for NFL 2025, week 1
restish pff teams nfl --season 2025 # teams and their franchise ids
restish pff players nfl --name Stafford # search the player directoryleagues tells you which seasons and weeks exist for each league, so check it rather than guess. Week ids are per league and do not line up between them:
| League | Preseason | Regular season | Postseason |
|---|---|---|---|
nfl |
-1 to -5 — -1 is the Hall of Fame game, so the ids run backwards in time |
1-18 |
28 Wild Card, 29 Divisional, 30 Conference Championship, 32 Super Bowl — there is no 31 |
ncaa |
none | 0-16 |
17 conference championships, 18 bowls, 19 semifinals, 20 championship |
So 17 and 18 are regular-season weeks in the NFL and postseason weeks in college football, and a span such as --week 18 --week-to 29 on an NFL report is three weeks, not twelve — spans follow the calendar, not id arithmetic. The team-* commands take these groups as --week-group REG, PO, REGPO (the default) or PRE (NFL only), or an explicit list with --week-ids.
players and teams are how you find the ids that the player and team reports take.
Leaderboards (facets)
League-wide tables with one row per player. Every parameter is optional:
restish pff passing --league nfl --season 2025
restish pff rushing --league nfl --season 2025 --week 1
restish pff receiving --league nfl --season 2025 --franchise 26
restish pff defense --league nfl --season 2025 --week 1,2,3passing, rushing, receiving, defense, blocking and special-teams are aliases for the facet-*-summary commands. There are 27 facet commands in all — passing under pressure, depth of target, coverage scheme, run direction and more; restish pff --help lists them under facet.
Seasons and weeks accept comma-separated lists (--season 2024,2025, --week 1,2,3). --franchise narrows to one team and --game to one game.
One player’s reports
Most player commands take the league and the player id you found with players; a few, such as player-position-pivot, also take the season. --help always shows the order:
restish pff player-passing-summary nfl 4924 --season 2025
restish pff player-rushing-summary nfl 4924 --season 2025 --week 1
restish pff player-position-pivot nfl 2025 4924PFF’s own team tables
The newer team-* commands are PFF’s own contract over the team page. They take the league (nfl or ncaa) and, for one team, its slug — los-angeles-rams — which team-directory lists alongside the numeric franchise id (26) the API accepts in its place:
restish pff team-directory nfl --season 2025 # every team: ids, slugs, colours, groups
restish pff team-report nfl los-angeles-rams passing --season 2025 # one of 19 player reports for a team
restish pff team-leaders nfl los-angeles-rams --season 2025 --group passing # a team's leaders, ranked league-wide
restish pff team-rushing-direction nfl los-angeles-rams --season 2025 # rushing by direction, per rusher and gapteam-stats (one stat category, every value ranked within a --scope such as nfc-west), team-roster, team-schedule and the others follow the same shape; restish pff --help lists all of them under team, and each command’s --help shows its choices — the 19 report names, the --category and --scope values, and so on. Restish flags are kebab-case even though the JSON keys are camelCase: --week-group REG|PO|REGPO picks the regular season, the playoffs or both, --week-ids 1,2,3 names weeks explicitly, and team-report also takes --week / --week-to for a span.
Every response is a table object: a columns array describing each column (key, label, type), rows — one flat, camelCase object per row, where a ranked value comes as <key> plus <key>Rank — and updatedAt, when the data behind it was last refreshed. Filter it the same way as any other command:
restish pff team-directory nfl --season 2025 -f body.rows -o table --rsh-columns name,abbreviation,slug,franchiseId
restish pff team-report nfl los-angeles-rams passing --season 2025 -f 'body.rows[0]' -o jsonShaping the output
Restish prints a readable, coloured body by default. These flags change that, and they work on every command:
| Flag | What it does |
|---|---|
-o json |
Plain JSON — the right choice when piping to jq or a file |
-o table |
A table; choose columns with --rsh-columns a,b,c, sort with --rsh-sort-by |
-o lines |
One value per line — for shell loops |
-f '…' |
Keep only part of the response (below) |
-v |
Also show the request and response headers |
Responses are objects with one top-level key — passing_summary, players, leagues, and so on — that holds the rows. Filters address it as body.<key>:
# The first row of the passing leaderboard, as JSON
restish pff passing --league nfl --season 2025 -f 'body.passing_summary[0]' -o json
# Four columns, as a table
restish pff passing --league nfl --season 2025 \
-f body.passing_summary -o table --rsh-columns player,team,yards,touchdowns
# Just the league slugs, one per line
restish pff leagues -f 'body.leagues[].slug' -o lines┌──────────────────┬──────┬───────┬────────────┐
│ player │ team │ yards │ touchdowns │
├──────────────────┼──────┼───────┼────────────┤
│ Matthew Stafford │ LA │ 5643 │ 52 │
│ Caleb Williams │ CHI │ 4780 │ 33 │
│ Bo Nix │ DEN │ 4351 │ 29 │
└──────────────────┴──────┴───────┴────────────┘Filters use Restish’s shorthand syntax; jq expressions are accepted too and detected automatically. Quote any filter that contains [] unless you ran restish shell setup.
Next: Exporting to CSV & files — the same commands, into spreadsheets and pipelines.