Skip to main content

Overview

The tif1 CLI gives access to Formula 1 data from the terminal. The CLI is built with Typer and Rich. It prints formatted output with progress indicators and tables. The CLI is designed for:
  • Quick data exploration - Browse events, sessions, and drivers without writing code
  • Performance testing - Benchmark data loading and cache performance
  • Cache management - Inspect and manage the local data cache
  • Debugging - Enable detailed logging to troubleshoot issues
  • Scripting - Integrate F1 data into shell scripts and automation workflows

Installation

The tif1 package installs the CLI automatically:
After installation, the tif1 command is available in the terminal. Verify the installation:

Global Options

All commands support standard help output:

Commands Reference

events - List Events for a Season

Display all Formula 1 events (Grand Prix weekends) for a specific year. Syntax:
Arguments:
  • year (required): Season year (1950-current)
Output:
  • Formatted table with event numbers and names
  • Total event count for the season
Examples:
Sample Output (tif1 events 2025):
The list includes testing events, such as Pre-Season Testing. The total can be higher than the number of Grand Prix weekends. Use Cases:
  • Discover available events for a season
  • Find the exact event name for use in other commands
  • Check the schedule of a specific year

sessions - List Sessions for an Event

Display all sessions available for a specific Grand Prix event. Syntax:
Arguments:
  • year (required): Season year (1950-current)
  • event (required): Event name (use quotes for multi-word names)
Output:
  • Formatted table with session numbers and names
  • Typical sessions include: Practice 1, Practice 2, Practice 3, Qualifying, Sprint, Sprint Qualifying, Race
Examples:
Sample Output (tif1 sessions 2024 Monaco):
The table title repeats the event name as typed, not the resolved name. Use Cases:
  • Determine available sessions for an event
  • Find the exact session name for data queries
  • Identify sprint weekends (which have Sprint and Sprint Qualifying sessions)

drivers - List Drivers in a Session

Display all drivers of a specific session, with their teams and car numbers. The rows are in classification order. Syntax:
Arguments:
  • year (required): Season year (1950-current)
  • event (required): Event name (use quotes for multi-word names)
  • session (required): Session name (use quotes for multi-word names)
Output:
  • Formatted table with driver codes, team names, and car numbers
  • Total driver count
  • Progress indicator during data loading
Examples:
Sample Output (tif1 drivers 2024 Monaco Qualifying):
Use Cases:
  • Identify which drivers participated in a session
  • Find driver codes for use in other commands
  • Verify team lineups for a specific event
  • Check for reserve drivers or substitutions

fastest - Show Fastest Laps

Display the fastest lap times for all drivers or a specific driver in a session. Syntax:
Arguments:
  • year (required): Season year (1950-current)
  • event (required): Event name (use quotes for multi-word names)
  • session (required): Session name (use quotes for multi-word names)
Options:
  • --driver <code> or -d <code>: Filter to a specific driver (3-letter code, case-sensitive)
Output:
  • All drivers mode: Sorted table of fastest laps with position, driver, team, and time
  • Single driver mode: The fastest lap time of the driver
  • Progress indicator during data loading
Examples:
Sample Output (All Drivers, tif1 fastest 2025 Bahrain Race):
Sample Output (Single Driver, -d VER):
A lap counts when its LapTime is set and the lap is not deleted. A driver without such a lap is not in the table. With --driver, such a driver gets No valid laps for <code>. An unknown code exits with DriverNotFoundError. Use Cases:
  • Compare driver performance in a session
  • Identify the fastest driver in qualifying or practice
  • Analyze individual driver lap times
  • Generate performance reports for specific drivers

cache-info - Show Cache Information

Display detailed information about the local tif1 cache: location, file count, and total size. Syntax:
Arguments: None Output:
  • Cache directory path
  • Number of cache files
  • Total cache size in megabytes
Examples:
Sample Output:
Use Cases:
  • Monitor cache disk usage
  • Verify cache location
  • Determine if cache needs cleaning
  • Troubleshoot cache-related issues
Cache Details: The tif1 cache uses SQLite with Write-Ahead Logging (WAL):
  • Main cache database: cache.sqlite - Stores session data, lap data, and metadata
  • WAL files: cache.sqlite-wal and cache.sqlite-shm - Transaction logs for concurrent access
  • In-memory cache: LRU caches for frequently accessed data (not shown in file count)
The cache stores:
  • Event schedules
  • Session metadata
  • Lap data
  • Telemetry data
  • Weather information
  • Race control messages

cache-clear - Clear Cache

Remove all cached data to force fresh data downloads. Syntax:
Options:
  • --yes or -y: Skip confirmation prompt (useful for scripts)
Output:
  • Confirmation prompt (unless --yes is used)
  • Success or cancellation message
Examples:
Sample Output (With Confirmation):
Sample Output (Without Confirmation):
Sample Output (Cancelled):
Use Cases:
  • Force fresh data downloads after data corrections
  • Troubleshoot cache corruption issues
  • Reset cache during development/testing
Warning: Clearing the cache removes all local data. The next access downloads all data again. The download time depends on the network speed and the amount of data requested. 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. To get the disk space back, delete the cache directory.

version - Show Version Information

Display the installed version of tif1. Syntax:
Arguments: None Output:
  • tif1 version number
Examples:
Sample Output:
Use Cases:
  • Verify installed version
  • Report version in bug reports
  • Confirm successful installation

debug - Debug Mode Session Loading

Load a session with debug-level logging enabled to troubleshoot issues or understand data loading behavior. Syntax:
Arguments:
  • year (required): Season year (1950-current)
  • event (required): Event name (use quotes for multi-word names)
  • session (required): Session name (use quotes for multi-word names)
Output:
  • Debug logs on stderr, showing:
    • CDN request URLs
    • Cache hits and cache writes
    • Lap loading steps
  • Session summary on stdout (driver count, lap count)
  • Progress indicator during loading
Examples:
Sample Output (tif1 debug 2025 Bahrain Race with an empty cache, shortened):
The session loads lazily, so Session loaded successfully! appears first. The data fetches start when the command reads the drivers and the laps. Use Cases:
  • Troubleshoot data loading issues
  • Understand cache behavior
  • Debug network connectivity problems
  • Report detailed information in bug reports
  • Verify data sources and CDN behavior
Debug Information Includes:
  • Cache operations (SQLite hits, frame-tier hits, writes)
  • CDN requests (source name and URL)
  • Retry, CDN fallback, and circuit breaker messages
  • HTTP connection pool statistics

Configuration

The CLI reads all tif1 configuration options from environment variables and from the .tif1rc configuration file.

Environment Variables

Key environment variables that affect CLI behavior:
No environment variable sets the log level. Use the debug command for debug logs.

Configuration File

Create a .tif1rc file in the home directory for persistent configuration:
See the Environment Variables documentation for complete details.

Advanced Usage

Scripting and Automation

The CLI is designed for use in shell scripts and automation workflows:

Performance Testing

Use the CLI to benchmark cache performance:

Pipeline Integration

Combine CLI commands with other tools:

Common Workflows

Exploring a New Season

Analyzing Driver Performance

Cache Management

Troubleshooting


Tips and Best Practices

Event and Session Names

  • Use quotes for multi-word names: "Abu Dhabi Grand Prix"
  • Single-word event names do not need quotes: Monaco
  • Session names are case-insensitive: Qualifying, qualifying, and Q all work
  • Use tif1 events and tif1 sessions to find exact names

Performance Optimization

  • The first data access is slower (cold cache)
  • Subsequent accesses are much faster (warm cache)
  • Use cache-clear sparingly to maintain performance
  • Use the debug command to see which CDN or cache tier serves each file

Error Handling

  • If a command fails, use the debug command for detailed error information
  • Check the internet connection for network-related errors
  • Verify event and session names are correct
  • Ensure the year is within the supported range (1950-current)

Cache Location

  • Default cache location varies by OS:
    • Linux/other POSIX: ~/.cache/tif1 or ~/.tif1
    • macOS: ~/Library/Caches/tif1
    • Windows: %LOCALAPPDATA%\Temp\tif1
  • Override the location with the TIF1_CACHE_DIR environment variable
  • Cache permissions are restricted to the user (0o700)

Troubleshooting

Command Not Found

If the tif1 command is not found after installation:

Network Errors

If network errors occur:

Cache Issues

If the cache is corrupt:

Data Not Found

If data is not available:


Support

For issues, questions, or feature requests:

Quick Reference

Last modified on October 30, 2026