Skip to main content
The tif1 CLI provides quick access to F1 data without writing Python code. It is a thin wrapper around the Python API. The data commands load data through tif1.get_events(), tif1.get_sessions(), or tif1.get_session() and print a table.

Installation

The CLI is included with tif1. Verify the installation:

Usage

The CLI has no global options other than the standard ones below. Behaviour such as the DataFrame backend or caching is controlled through environment variables or a .tif1rc file. Every command accepts --help, for example tif1 fastest --help.

Commands

events

List all events of a season, testing events included.
The list is the full schedule, so the total can exceed the number of Grands Prix. Testing events come last. Arguments:

sessions

List the sessions available for an event.
The table title repeats the event name as typed, not the resolved name. Arguments:

drivers

List the drivers, teams, and car numbers of a session.
Rows are in classification order (session.drivers_df): driver code, team, and car number. Arguments:

fastest

Show the fastest lap of every driver, sorted by time, or the fastest lap of one driver.
Times are lap times in seconds. Rich wraps a table title that is wider than the table. Options: A lap counts when its LapTime is set. A driver without any timed lap is left out of the table; with --driver the command prints No valid laps for CODE instead of a time.

results

Show the classification of a session: the official Ergast results merged into session.results (grid, status, points, race time or qualifying segments).
Options:

standings

Show the drivers’ (default) or constructors’ championship standings after a round. Without ROUND, the standings after the last completed round (the final standings of a past season).
Options:

cache-info

Show where the cache lives and how large it is.
The size counts the SQLite database and its WAL/SHM files. If no cache.sqlite* file exists yet, it counts every file in the cache directory. Set TIF1_CACHE_DIR to move the cache.

cache-clear

Delete all cached data. The command asks for confirmation unless --yes is given.
Options:
Any answer other than y prints Cache clear cancelled. The command deletes the rows of every cache table. The cache.sqlite file keeps its size, and SQLite reuses the free pages for new data.

version

Print the installed tif1 version.

debug

Load a session with debug logging enabled and print a short summary. Use it to see which CDN sources and cache tiers a load touches.
Output of tif1 debug 2025 "Monaco Grand Prix" Race with a warm cache:
The command calls tif1.setup_logging(logging.DEBUG). The timestamped log lines go to stderr, and the summary goes to stdout. Drivers and laps load lazily, so Session loaded successfully! appears before the fetch and cache log lines. On a cold cache, the log also shows the Trying CDN: jsDelivr - <url> request lines.

Environment Variables

The CLI reads the same configuration as the Python API. The most useful variables are:
For debug logs, use the debug command. See the environment variables reference for the full list.

Shell Completion

Typer generates completion scripts for bash, zsh, fish, and PowerShell.

Piping and Scripting

Commands print formatted tables, not machine-readable output. For scripting, grep the table or use the Python API directly.

Exit Codes

A misspelled event name does not fail. Event names are fuzzy-matched, so tif1 sessions 2025 "Monacco" logs Correcting user input 'Monacco' to 'Monaco Grand Prix' on stderr. It then exits 0 with the sessions of that event. Circuit, city, and country aliases resolve directly. A name that resembles no event, such as "Paris", exits 1 with EventNotFoundError in sessions, drivers, fastest, and debug. An alias of an event that is not on the calendar exits 1 with EventNotInSeasonError.

Best Practices

Use Quotes

Quote event names with spaces, for example "Monaco Grand Prix".

Check Availability

Use events and sessions to find the exact names before loading a session.

Keep the Cache

Repeated commands for the same session read from the SQLite cache. They finish in well under a second.

Switch to Python for Analysis

The CLI is for quick lookups. Lap filtering, telemetry, exports, and plots live in the Python API.
Last modified on October 30, 2026