f1-cli — Formula 1 Data CLI

A Go CLI wrapping the OpenF1 API for querying F1 telemetry, timing, and session data.

Installation

brew tap barronlroth/tap
brew install f1-cli

Or from source:

go install github.com/barronlroth/f1-cli/cmd/f1@latest

The binary name is f1.

Quick Reference

Global Flags (apply to all commands)

Flag	Description
--json	Output as JSON (default: table)
--csv	Output as CSV
--session KEY	Session key — number or latest
--meeting KEY	Meeting key — number or latest
--driver DRIVER	Driver number (44) or 3-letter acronym (HAM)
--limit N	Limit results returned
--filter EXPR	Raw API filter, repeatable (e.g. speed>=300)

Commands → API Endpoints

Command	Endpoint	What it returns
f1 drivers	/drivers	Driver info: name, team, number, acronym
f1 sessions	/sessions	Session list (FP1-3, Quali, Sprint, Race)
f1 meetings	/meetings	Grand Prix weekends (extra: --year, --country)
f1 laps	/laps	Lap times, sector times, speed traps
f1 telemetry	/car_data	Speed, RPM, gear, throttle, brake, DRS at ~3.7 Hz
f1 pit	/pit	Pit stop timing and duration
f1 positions	/position	Position changes throughout session
f1 intervals	/intervals	Gap to leader and car ahead (race only)
f1 standings drivers	/championship_drivers	Driver championship points (race sessions)
f1 standings teams	/championship_teams	Constructor standings (race sessions)
f1 weather	/weather	Track temp, air temp, humidity, wind, rain
f1 race-control	/race_control	Flags, safety car, incidents
f1 radio	/team_radio	Team radio recording URLs
f1 stints	/stints	Tire compound and stint laps
f1 overtakes	/overtakes	Position exchanges between drivers
f1 location	/location	Car XYZ position on track (~3.7 Hz)
f1 doctor	—	API connectivity check

Usage Patterns

Finding the right session

Most commands need --session. Start with latest for the most recent session, or find a specific one:

# List sessions for the latest meeting
f1 sessions --meeting latest

# Find a specific Grand Prix
f1 meetings --year 2025 --country Singapore

# Then use the session_key from the output
f1 laps --session 9161 --driver VER

Driver identification

The --driver flag accepts either a number or a 3-letter acronym. The CLI resolves acronyms automatically via the API.

# These are equivalent
f1 laps --session latest --driver 1
f1 laps --session latest --driver VER

Common driver acronyms: VER (Verstappen), NOR (Norris), HAM (Hamilton), LEC (Leclerc), PIA (Piastri), SAI (Sainz), RUS (Russell), ALO (Alonso).

Filtering with comparison operators

The --filter flag passes raw query params to the API. Supports >=, <=, >, < operators. Can be repeated.

# Cars going over 315 km/h
f1 telemetry --session 9159 --driver 55 --filter "speed>=315"

# Pit stops under 2.5 seconds
f1 pit --session latest --filter "stop_duration<2.5"

# Combine multiple filters
f1 telemetry --session latest --driver VER --filter "speed>=300" --filter "throttle>=95"

# Laps under 90 seconds
f1 laps --session latest --filter "lap_duration<90"

Output formats

# Default: aligned table
f1 drivers --session latest

# JSON for piping to jq or other tools
f1 telemetry --session latest --driver VER --json | jq '.[0].speed'

# CSV for spreadsheets
f1 laps --session latest --driver HAM --csv > hamilton_laps.csv

Common Workflows

"Who won the last race?"

# Always use standings for final race results
f1 standings drivers --session latest

Do NOT use f1 positions for race results. Positions is a time series — it records every position change throughout the session. Using --limit on positions gives you the start of the race, not the finish. Use f1 standings drivers for the final classification.

"Compare two drivers' lap times"

f1 laps --session latest --driver VER --json > /tmp/ver.json
f1 laps --session latest --driver NOR --json > /tmp/nor.json
# Then compare the JSON files

"What happened during the race?" (incidents, flags)

f1 race-control --session latest

"Tire strategy breakdown"

f1 stints --session latest --driver VER

"Weather conditions during the session"

f1 weather --session latest --limit 10

"Fastest pit stops"

f1 pit --session latest --filter "stop_duration<3" --json | jq 'sort_by(.stop_duration)'

Important Gotchas

• --limit is client-side only. The OpenF1 API does not support a limit query parameter. The CLI fetches all results then truncates locally. This means large telemetry/location queries still hit the API fully — use --filter to narrow server-side when possible.
• --filter is server-side. Filters like speed>=300 are sent to the API and reduce the response. Always prefer --filter over --limit for performance.
• positions is a time series, not a result. It records every position change during a session. To get final race results, use f1 standings drivers --session <key>, not f1 positions. Using positions --limit N gives you lap 1 grid order, not the finish.
• Driver numbers change between seasons. Don't hardcode driver numbers — use acronyms (VER, HAM, NOR) which the CLI resolves automatically per session.
• Norris is now #1. For the 2026 season, Lando Norris drives car #1 (as reigning champion). Verstappen is #3.

API Notes

• Data availability: Historical data from 2023 season onwards. No auth needed.
• Rate limits: 3 requests/second, 30 requests/minute (free tier). The CLI handles rate limiting internally with retry on 429.
• latest keyword: Works for both --session and --meeting to get the most recent.
• Intervals and overtakes: Only available during race sessions, not practice or qualifying.
• Championship standings: Only available for race sessions.
• Telemetry and location: High-frequency data (~3.7 Hz) — use --filter to narrow results server-side, then --limit to cap output.
• Off-season: --session latest returns 404 when no sessions exist. Use a known session_key from a past season instead.