Skip to main content

CLI Reference

The tif1 CLI provides a command-line interface for exploring Formula 1 data from the terminal. It is built with Typer for argument parsing. It uses Rich for colorful terminal output with tables and progress indicators. The CLI requires no configuration.

What is the tif1 CLI?

The tif1 CLI is a command-line tool. It gives access to Formula 1 data without writing Python code. It is designed for data analysts, F1 enthusiasts, and developers. It serves anyone who wants to explore F1 data from the terminal. The CLI has exactly eight commands: events, sessions, drivers, fastest, cache-info, cache-clear, version, and debug. Key Features:
  • Zero Configuration: Works out of the box after installation
  • Rich Terminal Output: Color-coded tables with Unicode borders
  • Automatic Caching: SQLite cache speeds up repeated queries
  • Progress Indicators: A progress bar while a session loads
  • Cross-Platform: Works on Linux, macOS, and Windows
  • Scriptable: Exit codes for scripts, and output without color codes when piped
  • Shared Configuration: Reads the same environment variables and .tif1rc file as the Python API

Overview

The CLI is designed for multiple use cases and user personas:

Use Cases

  1. Quick Data Exploration
    • View race calendars, session lists, driver lineups, and fastest laps
    • No Python code required - type a command and see the result
    • Explore names and data before writing analysis code
  2. Debugging & Development
    • Check that a session loads
    • Troubleshoot issues with debug logging
    • Identify network issues and cache behavior
  3. Cache Management
    • Show the cache location, file count, and size
    • Clear the cache to force fresh downloads
  4. Scripting & Automation
    • Integrate F1 data into shell scripts and automation workflows
    • Build CI/CD jobs that depend on F1 data
    • Branch on exit codes
  5. Learning & Discovery
    • Understand F1 data hierarchy (seasons → events → sessions → drivers)
    • Learn event naming conventions and session types
    • Discover what data is available before committing to analysis
  6. Performance Analysis
    • Compare fastest laps across sessions and drivers
    • Track driver performance throughout a race weekend
    • Compare qualifying and race pace
  7. Data Validation
    • Check driver participation in sessions
    • Check the lap count of a session with debug

Who Should Use the CLI?

  • Data Analysts: Quick data exploration and validation
  • F1 Enthusiasts: Instant access to race data and statistics
  • Developers: Testing and debugging data pipelines
  • DevOps Engineers: Automation and monitoring scripts
  • Researchers: Data collection for academic studies
  • Journalists: Quick fact-checking and statistics lookup
  • Content Creators: Gathering data for articles, videos, or social media

Performance Characteristics

  • Fast Startup: Commands import pandas and Rich only when they need them, so tif1 version returns at once
  • Cached Requests: A cached session loads in under 1 second (local SQLite read)
  • First Request: The time depends on the network. Data comes from jsDelivr, with Hugging Face and StaticDelivr as fallbacks.
  • Concurrent Safe: Multiple CLI instances can run at the same time. The SQLite cache runs in WAL mode.

Installation

The CLI is included with every tif1 installation. Typer and Rich are core dependencies of tif1, so no extra packages are necessary.

Standard Installation

Install tif1 using pip (Python 3.11 or higher required):
After installation, the tif1 command is available in the terminal of that Python environment. The CLI and the Python API share the installation, the cache, and the configuration.

Installation Methods

1. System-Wide Installation (requires admin/sudo):
2. User Installation (recommended for non-admin users):
3. Virtual Environment (recommended for development):
4. Development Installation (from source):

Verify Installation

Confirm the CLI is installed correctly and check the version:
Expected output:
If the command is not found, troubleshoot using these steps:
  1. Check Python Environment:
  2. Verify PATH Configuration:
  3. Locate tif1 Executable:
  4. Common Issues:
    • Virtual environment not activated: Run source venv/bin/activate (Linux/macOS) or venv\Scripts\activate (Windows)
    • User installation PATH issue: Add ~/.local/bin (Linux/macOS) or %APPDATA%\Python\Scripts (Windows) to PATH
    • Permission issues: Use pip install --user tif1 instead of system-wide installation

Upgrading

To upgrade to the latest version:

Uninstallation

To remove tif1:

Getting Started

First Commands

Walk through a complete workflow from discovering events to analyzing lap times: Step 1: Discover Available Events Start by listing all events in a season to see what data is available:
This shows all events of 2025, testing included. Note the exact event names for the next commands. Step 2: Check Event Sessions Pick an event and see what sessions are available:
This displays all sessions (Practice 1-3, Qualifying, Race) for Monaco. Note that sprint weekends have different session structures. Step 3: View Participating Drivers See which drivers participated in a specific session:
This loads the session data and displays all drivers with their teams and car numbers. The first run fetches data from the network. Later runs read the SQLite cache and are faster. Step 4: Analyze Lap Times View fastest lap times for all drivers:
Or check a specific driver’s fastest lap:
Step 5: Manage Cache Check the cache size and location:
Clear cache if needed:

Understanding the Data Hierarchy

F1 data in tif1 follows a clear hierarchy:
Example Navigation:

Common Patterns

Pattern 1: Weekend Analysis
Pattern 2: Driver Tracking
Pattern 3: Multi-Event Comparison
Pattern 4: Historical Analysis

Quick Reference Card


Quick Start

Get started with these common commands:

Global Usage Pattern

All commands follow a consistent, predictable pattern:
  • OPTIONS: Options before the command are --help, --install-completion, and --show-completion only
  • COMMAND: The action to perform (for example, events, sessions, drivers, fastest)
  • ARGS: Positional arguments in a fixed order (year, event, session), then command options such as --driver or --yes

Command Structure

Commands are organized hierarchically by data granularity:
  1. Season Level: events - Lists all events in a season
  2. Event Level: sessions - Lists all sessions in an event
  3. Session Level: drivers, fastest - Analyzes data within a session
  4. Utility Commands: cache-info, cache-clear, version, debug - Management and debugging

Getting Help

Every command has built-in help documentation:
The help output shows:
  • Command description
  • Arguments with their types and a [required] marker
  • Options with their short forms

Command Naming Conventions

  • Commands use lowercase with hyphens for multi-word names (for example, cache-info, cache-clear)
  • Arguments use natural language names (for example, year, event, session)
  • Options use double dashes for long form (--driver) and single dash for short form (-d)

Core Concepts

Understanding these core concepts helps with effective CLI use and helps avoid common pitfalls.

Event Names

Event names are the official Grand Prix names as they appear in the FIA Formula 1 World Championship calendar. The CLI resolves a name like tif1.get_event_by_name(). It tries a case-insensitive exact name first, then the alias table (“Monza”, “Silverstone”), then fuzzy matching. The alias table holds circuit, city, and country names. A fuzzy match needs a score of at least 70 and logs Correcting user input '...' to '...'. A name below that score fails with EventNotFoundError. The official name is the safest input. Standard Event Name Format: Most events follow the pattern: "[Location] Grand Prix" Examples:
  • “Monaco Grand Prix”
  • “British Grand Prix”
  • “Italian Grand Prix”
  • “Japanese Grand Prix”
  • “Australian Grand Prix”
Special Event Names: Some events have unique naming conventions:
  • “São Paulo Grand Prix” (note the special character ã)
  • “United States Grand Prix” (not “US Grand Prix”)
  • “Emilia Romagna Grand Prix” (not “Imola Grand Prix”)
  • “Mexico City Grand Prix” (not “Mexican Grand Prix”)
  • “Las Vegas Grand Prix” (not “Vegas Grand Prix”)
  • “Saudi Arabian Grand Prix” (not “Saudi Grand Prix”)
Why Official Names Help: The drivers, fastest, and debug commands resolve the name through tif1.get_session(). The sessions command resolves it through tif1.get_sessions(). Variants resolve to the same event, but a typo can resolve to a different race without an error:
The table titles of sessions, drivers, and fastest repeat the name as typed, not the resolved name. Shell Quoting Rules: Always use quotes around event names with spaces. The shell interprets unquoted spaces as argument separators:
Finding Exact Event Names: Always use the events command to get the exact event names:
Copy-Paste Workflow: The safest approach is to copy event names directly from the events output:

Session Names

Session names identify specific track sessions within an event. They are case-insensitive, and the abbreviations FP1, FP2, FP3, Q, S, SS, SQ, and R also work. Session names do not use fuzzy matching. Standard Weekend Format: Traditional race weekends have 5 sessions:
  1. “Practice 1”
  2. “Practice 2”
  3. “Practice 3”
  4. “Qualifying”
  5. “Race”
Sprint Weekend Format: Sprint weekends from 2024 have a different structure:
  1. “Practice 1”
  2. “Sprint Qualifying”
  3. “Sprint”
  4. “Qualifying”
  5. “Race”
Earlier sprint weekends differ. The 2023 weekends have “Sprint Shootout” in place of “Sprint Qualifying”. The 2021 and 2022 weekends have “Practice 1”, “Qualifying”, “Practice 2”, “Sprint”, and “Race”. Session Name Variations:
  • Practice sessions: “Practice 1”, “Practice 2”, “Practice 3” (note the space)
  • Qualifying: “Qualifying” or “Q” (not “Quali”)
  • Sprint qualifying: “Sprint Qualifying” (two words)
  • Sprint race: “Sprint” (not “Sprint Race”)
  • Main race: “Race” (not “Grand Prix” or “Main Race”)
Common Mistakes:
Discovering Available Sessions: Always use the sessions command to see what sessions are available for an event:
Sprint Weekend Detection: To check if an event is a sprint weekend:

Driver Codes

Drivers are identified by standardized three-letter codes. Code Format:
  • Always 3 uppercase letters
  • Usually derived from the driver’s surname
  • Unique across all drivers of a session
  • Case-sensitive in the CLI: VER works, and ver fails with DriverNotFoundError
Driver Codes of the 2025 Monaco Grand Prix: Finding Driver Codes: Use the drivers command to see all driver codes for a session:
Using Driver Codes: Driver codes are used with the --driver option:
Grid Changes Between Seasons: The grid changes from season to season:
Reserve and Substitute Drivers: Occasionally, reserve or substitute drivers participate:

Data Loading & Caching

The CLI implements caching to optimize performance and reduce network requests. Cache Architecture:
First Request (Cache Miss): When data is requested for the first time:
  1. Cache Lookup: CLI checks local SQLite cache
  2. Network Fetch: Data is downloaded from the CDN (jsDelivr primary; Hugging Face and StaticDelivr fallbacks)
  3. JSON Parsing: Raw JSON is parsed into structured data
  4. DataFrame Creation: Data is converted to pandas/polars DataFrame
  5. Cache Write: The payloads and the built lap table are stored in the cache
  6. Return: Data is displayed to user
The time of a first request depends on the network and on the CDN. Subsequent Requests (Cache Hit): When the same data is requested again:
  1. Cache Lookup: CLI checks local SQLite cache
  2. Cache Read: Data is loaded from disk
  3. Deserialization: Cached data is reconstructed
  4. Return: Data is displayed to user
A cached tif1 fastest run finishes in under a second. Performance Benefit:
Cache Location: Cache location is platform-specific: Custom Cache Location: Override the default cache location:
Cache Persistence:
  • Cache persists across CLI runs
  • Cache survives system reboots
  • Cache is shared across all CLI commands
  • Cache is shared with the Python API: both use tif1.get_cache() and the same directory
Cache Invalidation: Cached session data does not expire. Two kinds of entries expire:
  • The live schedule of the current season. tif1 downloads it again after schedule_ttl_hours (default 6).
  • The record of a file that no CDN has. It expires after missing_payloads_ttl_days (default 7).
To force fresh data:
Cache Size Management: Monitor cache growth:
Cache Behavior:
  • Each session is cached independently
  • Different data types (laps, telemetry) are cached separately
  • Cache keys include year, event, session, and data type
  • Cache is SQLite-based (ACID compliant, crash-safe)
Disabling Cache: For testing or debugging, disable caching. With TIF1_ENABLE_CACHE=false, the data commands do not read or write the SQLite cache.

Output Formatting

The CLI uses the Rich library for colorful terminal output with structured formatting. Table Components:
  1. Title: The arguments as typed (event name, year, and session)
  2. Headers: Column names
  3. Borders: Unicode box-drawing characters
  4. Data Rows: Color-coded values
  5. Summary: events and drivers print a Total: line
Color Scheme:
  • Cyan: Row numbers, driver codes in drivers, positions in fastest, progress text
  • Green: Event, session, and team names, success messages, the single-driver lap time
  • Yellow: Driver codes in fastest, the Cache clear cancelled message
  • Magenta: Lap times in fastest, car numbers in drivers
  • Red: The No valid laps for <code> message
  • Bold: Labels such as Total: and Cache location:
Table Example:
Rich wraps a table title that is wider than the table. Progress Indicators: The drivers, fastest, and debug commands show a progress bar while the session loads:
Terminal Compatibility:
  • Unicode Support: Uses Unicode box-drawing characters
  • Color Support: Automatically detects terminal color capabilities
  • Width Adaptation: Tables adapt to terminal width
Piping Behavior: When output is piped, Rich drops the color codes and keeps the box-drawing characters. The progress bar prints once, as the first line.
Plain Text Extraction: Data rows contain the │ character. Header rows use ┃, so a filter on │ keeps only the data rows:

Error Handling & Troubleshooting

When a command fails, Typer prints a Rich traceback. The last line names the exception and its message. The exit code is 1.

Common Error Messages

1. Unknown Event Name
Cause: The name resembles no event of the season (fuzzy score below 70). A typo such as “Monacco” still resolves, with a Correcting user input warning. Solution: Use tif1 events 2025 to find the exact event name. 2. Event Not on the Calendar
Cause: The name is an alias of an event that is not in that season. Solution: Use tif1 events 2025 to see the events of the season. 3. Session Not Found
Cause: The event does not have that session. Solution: Use tif1 sessions 2025 "Monaco Grand Prix" to find exact session names. 4. Driver Not Found
Cause: Invalid driver code, wrong case, or driver did not participate. Solution: Use tif1 drivers 2025 "Monaco Grand Prix" "Race" to see available drivers. 5. Network Failure The message has the form Network request failed: url='<url>'. It ends with status=<code> when the server sent a response. Cause: Slow network connection or CDN unavailable. Solution:
  • Check internet connection
  • Increase timeout: TIF1_TIMEOUT=60 tif1 fastest ...
  • Try again later
6. Data Not Available
Cause: The session has not taken place yet, or its data is not published. tif1 raises DataNotFoundError only when every CDN returns 404. Solution: Check if event has taken place and data is available. 7. Usage Errors Missing or invalid arguments exit with code 2. Typer prints the usage line and the error, for example Missing argument 'year'. or Invalid value for 'year': 'abc' is not a valid int.

Troubleshooting Workflow

Step 1: Verify Command Syntax
Step 2: Verify Event and Session Names
Step 3: Use Debug Mode
Step 4: Check Cache
Step 5: Verify Network

Platform-Specific Issues

Linux:
  • Permission denied: sudo chown -R $USER ~/.cache/tif1
  • Command not found: Add ~/.local/bin to PATH
  • Encoding issues: Set export LANG=en_US.UTF-8
macOS:
  • Command not found: Ensure Python bin directory in PATH
  • Special characters: Use UTF-8 terminal encoding
Windows:
  • Command not found: Add Python Scripts directory to PATH
  • PowerShell execution policy: Set-ExecutionPolicy RemoteSigned lets PowerShell run the virtual environment activation script
  • Path with spaces: Use quotes: "C:\Program Files\Python\Scripts\tif1"

Debug Mode

Enable verbose logging for troubleshooting:

Getting Help

Built-in Help:
Community Support:

Platform-Specific Guidance

Linux

Installation:
Cache Location:
Shell Integration:
Performance Tips:

macOS

Installation:
Cache Location:
Shell Integration:

Windows

Installation:
Cache Location:
PowerShell Usage:
Command Prompt (CMD) Usage:
Common Windows Issues:
  1. Execution Policy Error (virtual environment activation):
  2. Path with Spaces:
  3. Unicode Characters:

Commands

events - List Season Events

Display all Formula 1 events of a specific season year, testing included. Syntax:
Arguments: Description: The events command prints the event schedule of a season through tif1.get_events(). The rows are in schedule order, and testing events come last. Past seasons come from schedule files that ship with tif1. For the current and future seasons, tif1 downloads the FastF1 f1schedule file from GitHub. It keeps that file in the SQLite cache for schedule_ttl_hours (default 6). If the download fails, tif1 uses the bundled file. Output Format: The command displays a formatted table with:
  • #: Sequential event number (1-based index)
  • Event: Official event name (for example, “Monaco Grand Prix”, “British Grand Prix”)
  • Total count: Summary line showing total number of events
Examples:
Sample Output:
Use Cases:
  • Quick reference for race calendar
  • Planning data analysis for specific events
  • Verifying event names for use in other commands
  • Checking season length and schedule
Notes:
  • Other commands match event names case-insensitively, but the exact names from this table are the safest input
  • Use quotes around event names with spaces in subsequent commands
  • Past seasons work without a network connection

sessions - List Event Sessions

Display all sessions available for a specific Formula 1 event. Syntax:
Arguments: Description: The sessions command retrieves all practice, qualifying, sprint, and race sessions for a specific Grand Prix event. It reads the season schedule through tif1.get_sessions(). Different events may have different session structures (for example, sprint weekends have different formats). Typical session types include:
  • Practice 1, 2, 3: Free practice sessions (FP1, FP2, FP3)
  • Qualifying: Qualifying session
  • Sprint Qualifying: Sprint qualifying (on sprint weekends from 2024)
  • Sprint Shootout: Sprint qualifying (on 2023 sprint weekends)
  • Sprint: Sprint race (on sprint weekends)
  • Race: Main Grand Prix race
Output Format: The command displays a formatted table with:
  • #: Sequential session number
  • Session: Official session name
  • Title: Event name (as typed) and year
Examples:
Sample Output:
Sample Output (Sprint Weekend):
Use Cases:
  • Verify available sessions before loading data
  • Check session naming conventions
  • Understand event format (standard vs sprint weekend)
  • Plan analysis workflow
Important Notes:
  • Event names are case-insensitive, and fuzzy matching corrects near misses
  • A name that matches no event fails with EventNotFoundError and exit code 1
  • Always use quotes around event names with spaces
  • Use the session names from this table in subsequent commands
  • Not all events have the same session structure
Common Errors:

drivers - List Session Drivers

Display all drivers who participated in a specific session, along with their team and car number. Syntax:
Arguments: Description: The drivers command loads the session and prints session.drivers_df. The rows are in classification order. This is useful for verifying driver availability, checking team rosters, and getting driver codes for use in other commands. The command shows a progress indicator while loading session data from the network or cache. Output Format: The command displays a formatted table with:
  • Driver: Three-letter driver code (for example, VER, HAM, LEC)
  • Team: Full team name (for example, Red Bull Racing, Mercedes, Ferrari)
  • No.: Car number
  • Total count: Summary line showing total number of drivers
Examples:
Sample Output:
Use Cases:
  • Get driver codes for use with --driver option in other commands
  • Verify which drivers participated in a session
  • Check team lineups for a specific event
  • Identify reserve or substitute drivers
  • Confirm driver availability before detailed analysis
Performance Notes:
  • First run requires network fetch (shows progress indicator)
  • Subsequent runs use cached data and finish in under a second
  • Loading time depends on session data size and network speed
Important Notes:
  • Driver codes are standardized three-letter abbreviations (for example, VER, HAM, LEC)
  • Team names reflect the official team name at the time of the event
  • Use exact driver codes from this output in subsequent commands (codes are case-sensitive)
Common Patterns:

fastest - Show Fastest Laps

Display fastest lap times for all drivers or a specific driver in a session. Syntax:
Arguments: Options: Description: The fastest command finds the fastest lap of each driver in a session. This is particularly useful for qualifying analysis, race pace comparison, and performance evaluation. Behavior:
  • Without --driver: Calls session.get_fastest_laps(by_driver=True) and shows one row per driver, sorted by lap time (fastest first)
  • With --driver: Calls session.get_driver(code).get_fastest_lap() and prints one line with the lap time
Output Format: All Drivers Mode (default):
  • Pos: Position in fastest lap ranking (1 = fastest)
  • Driver: Three-letter driver code
  • Team: Team name
  • Time: Lap time in seconds (formatted to 3 decimal places)
Single Driver Mode (--driver specified):
  • Simple text output showing driver code and fastest lap time
Examples:
Sample Output (All Drivers):
Sample Output (Single Driver):
Use Cases:
  • Qualifying Analysis: Compare driver performance in qualifying sessions
  • Race Pace: Identify fastest race laps for pace analysis
  • Driver Comparison: Quickly compare lap times between drivers
  • Performance Tracking: Monitor driver/team performance across sessions
  • Quick Checks: Verify specific driver’s best performance
Performance Notes:
  • Loads the lap data of the session (network fetch on the first run)
  • Cached data makes subsequent runs faster (under 1 second)
Data Considerations:
  • A lap counts when its LapTime is set. The command does not filter out pit laps or deleted laps.
  • Times are shown in seconds with millisecond precision
  • A driver without a timed lap (for example, a DNS) is not in the table
Important Notes:
  • Driver codes must match exactly (case-sensitive: VER, not ver)
  • An unknown driver code exits with DriverNotFoundError
  • Times are sorted automatically (fastest first)
  • The --driver option is useful for quick single-driver checks
Common Patterns:
Error Handling:

results - Show the Session Classification

Display the official classification of a session: the Ergast results merged into session.results. Syntax:
Arguments: Options: Description: Races and sprints list position, car number, driver, team, grid, status and points. The last column is the winner’s total race time and every other driver’s gap. Qualifying lists the Q1, Q2 and Q3 times. Seasons before 2018 are served from Ergast data alone. Examples:

standings - Show Championship Standings

Display the drivers’ or constructors’ championship standings after a round. Syntax:
Arguments: Options: Examples:

cache-info - Display Cache Statistics

Show information about the tif1 cache: location, file count, and size. Syntax:
Arguments: None Description: The cache-info command provides a summary of the local tif1 cache. The cache stores downloaded F1 data to speed up subsequent requests. This is useful for monitoring cache growth, troubleshooting storage issues, and understanding cache behavior. Output Format: The command displays:
  • Cache location: Full filesystem path to the cache directory
  • Cache files: Number of cache.sqlite* files. If none exists, the command counts every file in the directory.
  • Total size: Combined size of these files in megabytes (MB)
Examples:
Sample Output (Linux):
Sample Output (Windows):
Sample Output (macOS):
Use Cases:
  • Monitor cache growth: Check how much disk space the cache is using
  • Troubleshoot performance: Verify cache is being used
  • Storage management: Identify if cache needs clearing
  • Debugging: Confirm cache location for manual inspection
  • Documentation: Record cache paths for team documentation
Cache Location by Platform: Cache Structure: The cache directory contains:
  • cache.sqlite: Main SQLite database file
  • cache.sqlite-wal: Write-Ahead Log file (WAL mode)
  • cache.sqlite-shm: Shared memory file (WAL mode)
The WAL and SHM files exist while a process has the database open. The cache-info command opens it too, so it usually counts 3 files. Understanding Cache Size: Cache size grows based on:
  • Number of sessions loaded: Each session adds lap data, telemetry, etc.
  • Data types requested: Telemetry data is larger than lap times
  • Historical data: Older seasons accumulate over time
Custom Cache Location: The default cache location can be overridden using the TIF1_CACHE_DIR environment variable:
Troubleshooting: If cache size seems incorrect:
  1. Check for multiple cache locations (environment variable override)
  2. Verify disk space availability
  3. Check file permissions on cache directory
  4. Consider clearing cache if corrupted: tif1 cache-clear
Related Commands:
  • tif1 cache-clear: Clear all cached data
  • Environment variable TIF1_CACHE_DIR: Override cache location
  • Environment variable TIF1_ENABLE_CACHE: Stop the data commands from using the cache

cache-clear - Clear Cache Database

--ergast clears only the Ergast tier (the Stats repository files and the Jolpica answers) and keeps the timing and telemetry payloads. Delete all cached data to force fresh data fetches. Syntax:
Options: Description: The cache-clear command removes all cached Formula 1 data from the local cache database. This is useful when:
  • Forcing fresh data: Suspect cached data is stale or corrupted
  • Troubleshooting: Debugging cache-related issues
  • Testing: Measuring cold-start performance
  • Data updates: Ensuring the latest data comes from the CDN
Important: Clearing the cache means all subsequent data requests need a network fetch. These requests are slower until the cache is rebuilt. Interactive Mode (default): By default, the command asks for confirmation before clearing:
Sample Output:
If the answer is ‘n’ or Enter is pressed (default is No):
Non-Interactive Mode (--yes flag): Skip the confirmation prompt for scripting or automation:
Sample Output:
Short Form:
Use Cases:
  1. Force Data Refresh:
  2. Automated Scripts:
  3. Troubleshooting:
What Gets Cleared: The command deletes the rows of every cache table:
  • Cached JSON payloads (drivers, laps, weather, messages, and the downloaded live schedule)
  • Cached telemetry payloads
  • Built lap and telemetry tables
  • The records of files that no CDN has
What Does not Get Cleared:
  • The cache directory and the cache.sqlite file. The file keeps its size, and SQLite reuses the free pages for new data. To get the disk space back, delete the cache directory.
  • Configuration files (.tif1rc)
  • The schedule files that ship with tif1
Performance Impact: After clearing cache:
  • First data load: Network fetch
  • Subsequent loads: Under 1 second (cached)
  • Cache rebuild: Automatic as commands are used
Safety Notes:
  • No data loss: Only cached data is removed; original data remains on CDN
  • Reversible: Cache rebuilds automatically as the CLI is used
  • No configuration changes: Configuration settings remain intact
  • Safe to interrupt: Can be cancelled with Ctrl+C before confirmation
Exit Codes:
  • 0: Cache cleared, or clear cancelled with an answer other than y
  • 1: Prompt interrupted with Ctrl+C or end of input (prints Aborted.), or an error during clearing
Related Commands:
  • tif1 cache-info: Check cache size before clearing
  • Environment variable TIF1_CACHE_DIR: Custom cache location

version - Show Version Information

Display the installed tif1 version number. Syntax:
Arguments: None Description: The version command prints tif1.__version__. This is useful for:
  • Troubleshooting: Verify the running version when reporting issues
  • Compatibility: Check whether the installed version has specific features
  • Updates: Confirm successful upgrade after running pip install --upgrade tif1
  • Documentation: Ensure documentation matches the installed version
Examples:
Sample Output:
Output Format: The output follows the pattern: tif1 version X.Y.Z Use Cases:
  1. Check Current Version:
  2. Verify Upgrade:
  3. Bug Reports:
  4. Scripting:
Version History: See the changelog for the changes in each release. Checking for Updates: To check if a newer version is available:
To upgrade to the latest version:
Exit Codes:
  • 0: Success (always succeeds)

debug - Debug Session Loading

Load a session with detailed debug logging enabled to troubleshoot issues. Syntax:
Arguments: Description: The debug command calls tif1.setup_logging(logging.DEBUG) and loads the session. Then it prints the driver count and the lap count. This is useful for:
  • Troubleshooting: Diagnose why data is not loading correctly
  • Network Issues: Identify connection problems or timeouts
  • Cache Behavior: Verify cache hits and cache writes
  • Development: Understand internal data flow
Unlike normal commands that show minimal output, debug displays:
  • CDN request URLs
  • Cache hits and cache writes
  • Lap loading steps
  • Retries and CDN fallbacks
  • HTTP connection pool statistics
Examples:
Sample Output (Cache Hit):
Sample Output (Cache Miss, 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:
  1. Diagnose Loading Failures:
  2. Cache Verification:
  3. Network Troubleshooting:
Debug Output Details: Each log line has the form <date> <time> - <logger> - <level> - <message>. The output includes:
  • Timestamps: Date and time to the second
  • Logger names: For example tif1.cdn, tif1.cache, tif1.async_fetch
  • URLs: Full CDN URLs being fetched
  • Cache operations: SQLite hits, frame-tier hits, and writes
  • Errors: Full stack traces for failures
Logging Levels: The debug command sets logging to DEBUG level, which shows:
  • DEBUG: Detailed internal operations
  • INFO: General information messages
  • WARNING: Potential issues
  • ERROR: Failures and exceptions
Output Destination: Debug output goes to:
  • stdout: The progress bar and the summary (Session loaded successfully!, driver and lap counts)
  • stderr: All log lines
This allows separating debug info from actual data:
Comparison with Normal Commands: Important Notes:
  • Output can be verbose (dozens of lines for a cold load)
  • URLs and file paths appear in the log
  • Not recommended for production scripts (use normal commands)
Exit Codes:
  • 0: Session loaded successfully
  • 1: Error loading session (network, data, cache issues)
Related Commands:
  • tif1 drivers: Normal driver listing (no debug output)
  • tif1 fastest: Normal fastest lap listing (no debug output)

Common Workflows

Explore Available Data

Start with high-level exploration and drill down to specific details:
This workflow helps with the following:
  • Discover available data without guessing event/session names
  • Verify data exists before writing Python code
  • Understand the data structure and hierarchy

Quick Performance Analysis

Compare driver performance across sessions:

Driver-Specific Analysis

Focus on a single driver’s performance:

Cache Management Workflow

Monitor and maintain cache health:

Troubleshooting Workflow

Diagnose and fix data loading issues:

Historical Data Analysis

Explore data from past seasons:

Sprint Weekend Analysis

Sprint weekends have different session structures:

Scripting & Automation

Integrate CLI into shell scripts:
Usage:

Data Validation Workflow

Verify data completeness and accuracy:

Batch Processing

Process multiple events efficiently:

Advanced Usage

Piping & Text Processing

Combine CLI with standard Unix tools:

Output Redirection

Save CLI output to files:

Environment Variable Usage

Customize CLI behavior with environment variables:

Conditional Execution

Use exit codes for conditional logic:

Parallel Processing

Run multiple CLI commands in parallel:

JSON Output

The CLI has no JSON output. Parse the table output, or use the Python API for structured data:

Tips & Best Practices

General Tips

  1. Always use quotes for multi-word names:
  2. Use tab completion (after tif1 --install-completion):
  3. Check help when unsure:
  4. Verify event names first:
  5. Use short options for speed:

Performance Tips

  1. Let cache warm up:
  2. Monitor cache size:
  3. Keep the cache:

Scripting Tips

  1. Handle errors gracefully:
  2. Use variables for reusability:
  3. Suppress output when needed:
  4. Check exit codes:

Troubleshooting Tips

  1. Start with debug mode:
  2. Clear cache when in doubt:
  3. Check version compatibility:
  4. Verify network connectivity:

Data Quality Tips

  1. Verify driver count:
  2. Check for missing data:
  3. Compare across sessions:
  4. Use historical data for validation:

Exit Codes

  • 0: Success
  • 1: Any exception (network, data not found, driver not found, invalid session); Typer prints the traceback
  • 2: Invalid arguments (missing argument, wrong type, unknown command)

Environment Variables

The CLI respects the same environment variables as the Python API for consistent behavior across interfaces:

Available Environment Variables

Use the debug command for debug logs. See the environment variables reference for the full list.

Usage Examples

Custom Cache Directory:
Use Polars Backend:
Disable Caching:
Increase Timeout:
Adjust Retry Behavior:

Configuration File

For persistent settings, tif1 reads a JSON file named .tif1rc in the home directory. The keys are the lowercase configuration names, such as cache_dir for TIF1_CACHE_DIR:
TIF1_CONFIG_FILE points tif1 to another file. A .tif1rc in the working directory is read only when TIF1_TRUST_CWD_CONFIG=true. Shell profiles can also hold the variables: Linux/macOS (~/.bashrc or ~/.zshrc):
Windows PowerShell ($PROFILE):

Environment Variable Precedence

When multiple configuration sources exist, precedence is:
  1. Environment variable (highest priority), set for one command or exported in the shell
  2. Configuration file (.tif1rc, JSON)
  3. Default value (lowest priority)

Advanced Topics

Performance Optimization

1. Parallel Processing Process multiple sessions simultaneously:
2. Cache Warming Pre-populate cache for faster subsequent access:
3. Batch Processing Process multiple events efficiently:

Integration with Other Tools

1. jq (JSON Processing) While CLI does not output JSON directly, table output can be converted:
2. awk (Text Processing)
3. gnuplot (Visualization)
4. Database Import

CI/CD Integration

GitHub Actions Example:
GitLab CI Example:
Jenkins Pipeline Example:

Docker Integration

Dockerfile:
Usage:

Monitoring and Logging

1. Command Logging Track all CLI usage:
2. Performance Monitoring Measure command execution time:
3. Error Tracking Capture and log errors:

Security Considerations

1. Cache Security tif1 creates the cache directory with mode 0o700 (owner only). Check the permissions:
2. Network Security All data requests use HTTPS:
The HTTP session sets trust_env = False, so no request pays for environment lookups. The proxies are resolved once when the session is created. That covers the HTTPS_PROXY, HTTP_PROXY and NO_PROXY variables on every platform, and the system proxy setting on Windows. Set the variables before the first request. 3. Input Validation Sanitize user input in scripts:

Testing and Validation

1. Smoke Tests Verify CLI functionality:
2. Data Validation Verify data integrity:
3. Regression Testing Compare outputs across versions:

Best Practices

General Best Practices

  1. Always Quote Multi-Word Arguments
  2. Use Exact Names from CLI Output
  3. Check Help When Unsure
  4. Use Short Options for Speed
  5. Use Tab Completion

Performance Best Practices

  1. Let Cache Warm Up
  2. Monitor Cache Size

Scripting Best Practices

  1. Handle Errors Gracefully
  2. Use Variables for Reusability
  3. Suppress Output When Needed
  4. Check Exit Codes
  5. Use Functions for Repeated Tasks

Data Quality Best Practices

  1. Verify Driver Count
  2. Check for Missing Data
  3. Compare Across Sessions
  4. Use Historical Data for Validation

Security Best Practices

  1. Validate User Input
  2. Keep the Cache Private
  3. Be Cautious with Piping

Maintenance Best Practices

  1. Keep tif1 Updated
  2. Monitor Cache Growth
  3. Free Disk Space
  4. Document the Workflows

Frequently Asked Questions (FAQ)

General Questions

Q: Is the CLI free to use? A: Yes, tif1 CLI is completely free and open-source. Q: Do I need an API key? A: No, tif1 CLI does not require any API keys or authentication. Q: What data is available? A: Lap times, telemetry, weather and race control messages from 2018 onwards, and Ergast results, lap times and standings from 1950 onwards. The CLI shows schedules, drivers, fastest laps, classifications and standings. Q: Can I use this for commercial purposes? A: tif1 is released under the MIT License. Read the LICENSE file for the terms.

Technical Questions

Q: Why is the first command slow? A: The first request fetches data from the network and caches it. Subsequent requests are much faster. Q: How much disk space does the cache use? A: It depends on the sessions and the data types loaded. Check with tif1 cache-info. Q: Can I use this offline? A: Past-season schedules ship with tif1, so events and sessions work offline. Sessions in the cache load offline too. Q: Does the CLI support Python 2? A: No, Python 3.11 or higher is required (3.11 through 3.15 are supported). Q: Can I run multiple CLI instances simultaneously? A: Yes. The SQLite cache runs in WAL mode, so several processes can share it.

Data Questions

Q: Why is driver X missing from the results? A: The driver did not take part in that session, or has no timed lap (for example, a DNS). Q: Can I get telemetry data via CLI? A: No. The CLI shows lap times and driver info. Use the Python API for telemetry.

Troubleshooting Questions

Q: Command not found error? A: Ensure tif1 is installed and the Python Scripts directory is in the PATH. Q: Permission denied error? A: Check cache directory permissions or use a custom cache location. Q: Network timeout error? A: Increase timeout with TIF1_TIMEOUT=60 or check the internet connection. Q: Cache corruption error? A: Clear cache with tif1 cache-clear -y and try again.

Changelog

The changes in each release are in the changelog.

Contributing

Contributions to improve the CLI are welcome. These are the ways to help:

Reporting Issues

  1. Check existing issues on GitHub
  2. Provide detailed error messages and steps to reproduce
  3. Include the OS, Python version, and tif1 version
  4. Use tif1 debug output when relevant

Suggesting Features

  1. Open a GitHub issue with the “enhancement” label
  2. Describe the use case and expected behavior
  3. Provide examples of how the feature would be used

Contributing Code

  1. Fork the repository
  2. Create a feature branch
  3. Make the changes with tests
  4. Submit a pull request
See the contributing guide for the development setup.

Documentation

Help improve this documentation:
  • Fix typos and clarify confusing sections
  • Add more examples and use cases
  • Translate to other languages

License

tif1 CLI is released under the MIT License. See LICENSE file for details.

Support


Acknowledgments

  • Typer: CLI framework
  • Rich: Terminal formatting
  • pandas/polars: Data processing
  • niquests: HTTP client
  • TracingInsights: Data source
Last modified on October 30, 2026