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: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:
year(required): Season year (1950-current)
- Formatted table with event numbers and names
- Total event count for the season
tif1 events 2025):
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:
year(required): Season year (1950-current)event(required): Event name (use quotes for multi-word names)
- Formatted table with session numbers and names
- Typical sessions include: Practice 1, Practice 2, Practice 3, Qualifying, Sprint, Sprint Qualifying, Race
tif1 sessions 2024 Monaco):
- 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:
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)
- Formatted table with driver codes, team names, and car numbers
- Total driver count
- Progress indicator during data loading
tif1 drivers 2024 Monaco Qualifying):
- 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:
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)
--driver <code>or-d <code>: Filter to a specific driver (3-letter code, case-sensitive)
- 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
tif1 fastest 2025 Bahrain Race):
-d VER):
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:
- Cache directory path
- Number of cache files
- Total cache size in megabytes
- Monitor cache disk usage
- Verify cache location
- Determine if cache needs cleaning
- Troubleshoot cache-related issues
- Main cache database:
cache.sqlite- Stores session data, lap data, and metadata - WAL files:
cache.sqlite-walandcache.sqlite-shm- Transaction logs for concurrent access - In-memory cache: LRU caches for frequently accessed data (not shown in file count)
- 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:
--yesor-y: Skip confirmation prompt (useful for scripts)
- Confirmation prompt (unless
--yesis used) - Success or cancellation message
- Force fresh data downloads after data corrections
- Troubleshoot cache corruption issues
- Reset cache during development/testing
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:
- tif1 version number
- 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:
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)
- 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
tif1 debug 2025 Bahrain Race with an empty cache, shortened):
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
- 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:debug command for debug logs.
Configuration File
Create a.tif1rc file in the home directory for persistent configuration:
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, andQall work - Use
tif1 eventsandtif1 sessionsto find exact names
Performance Optimization
- The first data access is slower (cold cache)
- Subsequent accesses are much faster (warm cache)
- Use
cache-clearsparingly to maintain performance - Use the
debugcommand to see which CDN or cache tier serves each file
Error Handling
- If a command fails, use the
debugcommand 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/tif1or~/.tif1 - macOS:
~/Library/Caches/tif1 - Windows:
%LOCALAPPDATA%\Temp\tif1
- Linux/other POSIX:
- Override the location with the
TIF1_CACHE_DIRenvironment variable - Cache permissions are restricted to the user (0o700)
Troubleshooting
Command Not Found
If thetif1 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:Related Documentation
- Python API Reference - Use tif1 programmatically
- Caching Strategy - Understand cache behavior
- Environment Variables - Configure tif1 settings
- Data Flow - Learn how data is fetched and processed
Support
For issues, questions, or feature requests:- GitHub Issues: TracingInsights/tif1
- Documentation: tif1.tracinginsights.com