CLI Reference
Thetif1 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
.tif1rcfile as the Python API
Overview
The CLI is designed for multiple use cases and user personas:Use Cases
-
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
-
Debugging & Development
- Check that a session loads
- Troubleshoot issues with debug logging
- Identify network issues and cache behavior
-
Cache Management
- Show the cache location, file count, and size
- Clear the cache to force fresh downloads
-
Scripting & Automation
- Integrate F1 data into shell scripts and automation workflows
- Build CI/CD jobs that depend on F1 data
- Branch on exit codes
-
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
-
Performance Analysis
- Compare fastest laps across sessions and drivers
- Track driver performance throughout a race weekend
- Compare qualifying and race pace
-
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 versionreturns 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):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):Verify Installation
Confirm the CLI is installed correctly and check the version:-
Check Python Environment:
-
Verify PATH Configuration:
-
Locate tif1 Executable:
-
Common Issues:
- Virtual environment not activated: Run
source venv/bin/activate(Linux/macOS) orvenv\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 tif1instead of system-wide installation
- Virtual environment not activated: Run
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:Understanding the Data Hierarchy
F1 data in tif1 follows a clear hierarchy:Common Patterns
Pattern 1: Weekend AnalysisQuick Reference Card
Quick Start
Get started with these common commands:Global Usage Pattern
- OPTIONS: Options before the command are
--help,--install-completion, and--show-completiononly - 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
--driveror--yes
Command Structure
Commands are organized hierarchically by data granularity:- Season Level:
events- Lists all events in a season - Event Level:
sessions- Lists all sessions in an event - Session Level:
drivers,fastest- Analyzes data within a session - Utility Commands:
cache-info,cache-clear,version,debug- Management and debugging
Getting Help
Every command has built-in help documentation:- 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 liketif1.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”
- “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”)
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:
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:
events command to get the exact event names:
events output:
Session Names
Session names identify specific track sessions within an event. They are case-insensitive, and the abbreviationsFP1, 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:
- “Practice 1”
- “Practice 2”
- “Practice 3”
- “Qualifying”
- “Race”
- “Practice 1”
- “Sprint Qualifying”
- “Sprint”
- “Qualifying”
- “Race”
- 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”)
sessions command to see what sessions are available for an event:
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:
VERworks, andverfails withDriverNotFoundError
Finding Driver Codes:
Use the
drivers command to see all driver codes for a session:
--driver option:
Data Loading & Caching
The CLI implements caching to optimize performance and reduce network requests. Cache Architecture:- Cache Lookup: CLI checks local SQLite cache
- Network Fetch: Data is downloaded from the CDN (jsDelivr primary; Hugging Face and StaticDelivr fallbacks)
- JSON Parsing: Raw JSON is parsed into structured data
- DataFrame Creation: Data is converted to pandas/polars DataFrame
- Cache Write: The payloads and the built lap table are stored in the cache
- Return: Data is displayed to user
- Cache Lookup: CLI checks local SQLite cache
- Cache Read: Data is loaded from disk
- Deserialization: Cached data is reconstructed
- Return: Data is displayed to user
tif1 fastest run finishes in under a second.
Performance Benefit:
Custom Cache Location:
Override the default cache location:
- 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
- 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).
- 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)
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:- Title: The arguments as typed (event name, year, and session)
- Headers: Column names
- Borders: Unicode box-drawing characters
- Data Rows: Color-coded values
- Summary:
eventsanddriversprint aTotal:line
- Cyan: Row numbers, driver codes in
drivers, positions infastest, progress text - Green: Event, session, and team names, success messages, the single-driver lap time
- Yellow: Driver codes in
fastest, theCache clear cancelledmessage - Magenta: Lap times in
fastest, car numbers indrivers - Red: The
No valid laps for <code>message - Bold: Labels such as
Total:andCache location:
drivers, fastest, and debug commands show a progress bar while the session loads:
- Unicode Support: Uses Unicode box-drawing characters
- Color Support: Automatically detects terminal color capabilities
- Width Adaptation: Tables adapt to terminal width
│ 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 is1.
Common Error Messages
1. Unknown Event NameCorrecting user input warning.
Solution: Use tif1 events 2025 to find the exact event name.
2. Event Not on the Calendar
tif1 events 2025 to see the events of the season.
3. Session Not Found
tif1 sessions 2025 "Monaco Grand Prix" to find exact session names.
4. Driver Not Found
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
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 SyntaxPlatform-Specific Issues
Linux:- Permission denied:
sudo chown -R $USER ~/.cache/tif1 - Command not found: Add
~/.local/binto PATH - Encoding issues: Set
export LANG=en_US.UTF-8
- Command not found: Ensure Python bin directory in PATH
- Special characters: Use UTF-8 terminal encoding
- Command not found: Add Python Scripts directory to PATH
- PowerShell execution policy:
Set-ExecutionPolicy RemoteSignedlets 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:- GitHub Issues: https://github.com/TracingInsights/tif1/issues
- Documentation: https://tif1.tracinginsights.com
Platform-Specific Guidance
Linux
Installation:macOS
Installation:Windows
Installation:-
Execution Policy Error (virtual environment activation):
-
Path with Spaces:
-
Unicode Characters:
Commands
events - List Season Events
Display all Formula 1 events of a specific season year, testing included.
Syntax:
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
- Quick reference for race calendar
- Planning data analysis for specific events
- Verifying event names for use in other commands
- Checking season length and schedule
- 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:
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
- #: Sequential session number
- Session: Official session name
- Title: Event name (as typed) and year
- Verify available sessions before loading data
- Check session naming conventions
- Understand event format (standard vs sprint weekend)
- Plan analysis workflow
- Event names are case-insensitive, and fuzzy matching corrects near misses
- A name that matches no event fails with
EventNotFoundErrorand exit code1 - 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
drivers - List Session Drivers
Display all drivers who participated in a specific session, along with their team and car number.
Syntax:
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
- Get driver codes for use with
--driveroption 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
- 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
- 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)
fastest - Show Fastest Laps
Display fastest lap times for all drivers or a specific driver in a session.
Syntax:
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: Callssession.get_fastest_laps(by_driver=True)and shows one row per driver, sorted by lap time (fastest first) - With
--driver: Callssession.get_driver(code).get_fastest_lap()and prints one line with the lap time
- 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)
--driver specified):
- Simple text output showing driver code and fastest lap time
- 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
- Loads the lap data of the session (network fetch on the first run)
- Cached data makes subsequent runs faster (under 1 second)
- A lap counts when its
LapTimeis 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
- Driver codes must match exactly (case-sensitive: VER, not ver)
- An unknown driver code exits with
DriverNotFoundError - Times are sorted automatically (fastest first)
- The
--driveroption is useful for quick single-driver checks
results - Show the Session Classification
Display the official classification of a session: the Ergast results merged into session.results.
Syntax:
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:
Options:
Examples:
cache-info - Display Cache Statistics
Show information about the tif1 cache: location, file count, and size.
Syntax:
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)
- 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 Structure:
The cache directory contains:
cache.sqlite: Main SQLite database filecache.sqlite-wal: Write-Ahead Log file (WAL mode)cache.sqlite-shm: Shared memory file (WAL mode)
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
TIF1_CACHE_DIR environment variable:
- Check for multiple cache locations (environment variable override)
- Verify disk space availability
- Check file permissions on cache directory
- Consider clearing cache if corrupted:
tif1 cache-clear
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:
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
--yes flag):
Skip the confirmation prompt for scripting or automation:
-
Force Data Refresh:
-
Automated Scripts:
-
Troubleshooting:
- 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
- The cache directory and the
cache.sqlitefile. 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
- First data load: Network fetch
- Subsequent loads: Under 1 second (cached)
- Cache rebuild: Automatic as commands are used
- 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
0: Cache cleared, or clear cancelled with an answer other thany1: Prompt interrupted with Ctrl+C or end of input (printsAborted.), or an error during clearing
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:
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
tif1 version X.Y.Z
Use Cases:
-
Check Current Version:
-
Verify Upgrade:
-
Bug Reports:
-
Scripting:
0: Success (always succeeds)
debug - Debug Session Loading
Load a session with detailed debug logging enabled to troubleshoot issues.
Syntax:
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
debug displays:
- CDN request URLs
- Cache hits and cache writes
- Lap loading steps
- Retries and CDN fallbacks
- HTTP connection pool statistics
Session loaded successfully! appears first. The data fetches start when the command reads the drivers and the laps.
Use Cases:
-
Diagnose Loading Failures:
-
Cache Verification:
-
Network Troubleshooting:
<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
debug command sets logging to DEBUG level, which shows:
- DEBUG: Detailed internal operations
- INFO: General information messages
- WARNING: Potential issues
- ERROR: Failures and exceptions
- stdout: The progress bar and the summary (
Session loaded successfully!, driver and lap counts) - stderr: All log lines
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)
0: Session loaded successfully1: Error loading session (network, data, cache issues)
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:- 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: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
-
Always use quotes for multi-word names:
-
Use tab completion (after
tif1 --install-completion): -
Check help when unsure:
-
Verify event names first:
-
Use short options for speed:
Performance Tips
-
Let cache warm up:
-
Monitor cache size:
-
Keep the cache:
Scripting Tips
-
Handle errors gracefully:
-
Use variables for reusability:
-
Suppress output when needed:
-
Check exit codes:
Troubleshooting Tips
-
Start with debug mode:
-
Clear cache when in doubt:
-
Check version compatibility:
-
Verify network connectivity:
Data Quality Tips
-
Verify driver count:
-
Check for missing data:
-
Compare across sessions:
-
Use historical data for validation:
Exit Codes
0: Success1: Any exception (network, data not found, driver not found, invalid session); Typer prints the traceback2: 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: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):
Environment Variable Precedence
When multiple configuration sources exist, precedence is:-
Environment variable (highest priority), set for one command or exported in the shell
-
Configuration file (
.tif1rc, JSON) - Default value (lowest priority)
Advanced Topics
Performance Optimization
1. Parallel Processing Process multiple sessions simultaneously:Integration with Other Tools
1. jq (JSON Processing) While CLI does not output JSON directly, table output can be converted:CI/CD Integration
GitHub Actions Example:Docker Integration
Dockerfile:Monitoring and Logging
1. Command Logging Track all CLI usage:Security Considerations
1. Cache Security tif1 creates the cache directory with mode0o700 (owner only). Check the permissions:
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:Best Practices
General Best Practices
-
Always Quote Multi-Word Arguments
-
Use Exact Names from CLI Output
-
Check Help When Unsure
-
Use Short Options for Speed
-
Use Tab Completion
Performance Best Practices
-
Let Cache Warm Up
-
Monitor Cache Size
Scripting Best Practices
-
Handle Errors Gracefully
-
Use Variables for Reusability
-
Suppress Output When Needed
-
Check Exit Codes
-
Use Functions for Repeated Tasks
Data Quality Best Practices
-
Verify Driver Count
-
Check for Missing Data
-
Compare Across Sessions
-
Use Historical Data for Validation
Security Best Practices
-
Validate User Input
-
Keep the Cache Private
-
Be Cautious with Piping
Maintenance Best Practices
-
Keep tif1 Updated
-
Monitor Cache Growth
-
Free Disk Space
-
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 withtif1 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 withTIF1_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
- Check existing issues on GitHub
- Provide detailed error messages and steps to reproduce
- Include the OS, Python version, and tif1 version
- Use
tif1 debugoutput when relevant
Suggesting Features
- Open a GitHub issue with the “enhancement” label
- Describe the use case and expected behavior
- Provide examples of how the feature would be used
Contributing Code
- Fork the repository
- Create a feature branch
- Make the changes with tests
- Submit a pull request
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
- Documentation: https://tif1.tracinginsights.com
- GitHub Issues: https://github.com/TracingInsights/tif1/issues
Acknowledgments
- Typer: CLI framework
- Rich: Terminal formatting
- pandas/polars: Data processing
- niquests: HTTP client
- TracingInsights: Data source