CLI Commands

The tif1 CLI provides quick access to F1 data without writing Python code.

Installation

The CLI is included with tif1. Verify installation:

tif1 --version

Global Options

These options work with all commands.

tif1 [OPTIONS] COMMAND [ARGS]

Option	Description
`--help`	Show help message and exit
`--version`	Show version and exit
`--lib [pandas\|polars]`	Choose DataFrame lib
`--no-cache`	Disable caching for this command
`--debug`	Enable debug logging

Commands

events

List all events (Grand Prix) for a given year.

tif1 events [YEAR]

Example
Output

tif1 events 2025

F1 Calendar
    ================
Bahrain Grand Prix
Saudi Arabian Grand Prix
Australian Grand Prix
Japanese Grand Prix
    ...

Options:

Option	Description
`--json`	Output as JSON
`--csv`	Output as CSV

sessions

List available sessions for a specific event.

tif1 sessions [YEAR] [EVENT]

Example
Output

tif1 sessions 2025 "Monaco Grand Prix"

    Available Sessions:
    - Practice 1
    - Practice 2
    - Practice 3
    - Qualifying
    - Race

laps

Fetch and display lap data.

tif1 laps [YEAR] [EVENT] [SESSION]

Example
Output

tif1 laps 2025 "Monaco Grand Prix" "Race"

    Loaded 1,247 laps for 20 drivers

    Fastest Laps:
    1. VER - 1:12.345
    2. LEC - 1:12.567
    3. HAM - 1:12.789
    ...

Options:

Option	Description
`--driver TEXT`	Filter to specific driver (3-letter code)
`--fastest`	Show only fastest laps
`--export PATH`	Export to file (CSV, JSON, or Parquet)
`--limit INT`	Limit number of rows displayed

Examples:

# Get all laps for Verstappen
tif1 laps 2025 "Monaco" "Race" --driver VER

# Export to CSV
tif1 laps 2025 "Monaco" "Race" --export laps.csv

# Show top 10 fastest laps
tif1 laps 2025 "Monaco" "Race" --fastest --limit 10

telemetry

Fetch telemetry data for a specific lap.

tif1 telemetry [YEAR] [EVENT] [SESSION] [DRIVER] [LAP_NUMBER]

Example
Output

tif1 telemetry 2025 "Silverstone" "Race" VER 15

    Telemetry for VER Lap 15
    ========================
    Duration: 87.234s
    Top Speed: 327 km/h
    Avg Speed: 215 km/h

    Samples: 349 data points

Options:

Option	Description
`--export PATH`	Export telemetry to file
`--plot`	Generate and display a plot
`--columns TEXT`	Comma-separated columns to display

Examples:

# Export telemetry
tif1 telemetry 2025 "Silverstone" "Race" VER 15 --export tel.csv

# Plot speed trace
tif1 telemetry 2025 "Silverstone" "Race" VER 15 --plot

# Show specific columns
tif1 telemetry 2025 "Silverstone" "Race" VER 15 --columns "Speed,Throttle,Brake"

drivers

List drivers in a session.

tif1 drivers [YEAR] [EVENT] [SESSION]

Example
Output

tif1 drivers 2025 "Monaco" "Race"

    Drivers in 2025 Monaco Grand Prix - Race
    =========================================
    VER - Max Verstappen (Red Bull Racing) #33
    HAM - Lewis Hamilton (Mercedes) #44
    LEC - Charles Leclerc (Ferrari) #16
    ...

Options:

Option	Description
`--json`	Output as JSON
`--team TEXT`	Filter by team name

weather

Display weather data for a session.

tif1 weather [YEAR] [EVENT] [SESSION]

Example
Output

tif1 weather 2025 "Singapore" "Race"

    Weather Data - 2025 Singapore GP Race
    ======================================
    Air Temp: 28-31°C
    Track Temp: 35-42°C
    Humidity: 75-82%
    Rainfall: Yes (Lap 15-23)
    Wind: 5-8 m/s from NE

Options:

Option	Description
`--export PATH`	Export weather data to file
`--summary`	Show summary statistics only

compare

Compare lap times between drivers.

tif1 compare [YEAR] [EVENT] [SESSION] [DRIVER1] [DRIVER2]

Example
Output

tif1 compare 2025 "Monaco" "Qualifying" VER LEC

    Comparison: VER vs LEC
    ======================
    VER Fastest: 1:10.234
    LEC Fastest: 1:10.456
    Delta: +0.222s (LEC slower)

    Sector Comparison:
    S1: VER +0.045s
    S2: LEC -0.012s
    S3: VER +0.189s

Options:

Option	Description
`--lap-number INT`	Compare specific lap numbers
`--fastest`	Compare fastest laps (default)
`--plot`	Generate comparison plot

cache

Manage the local cache.

tif1 cache [COMMAND]

Subcommands:

Command	Description
`info`	Show cache statistics
`clear`	Clear all cached data
`size`	Show cache size on disk
`list`	List cached sessions

Examples:

# Show cache info
tif1 cache info

# Clear cache
tif1 cache clear

# Show cache size
tif1 cache size

config

Display or modify configuration.

tif1 config [COMMAND]

Subcommands:

Command	Description
`show`	Display current configuration
`set KEY VALUE`	Set a configuration value
`get KEY`	Get a configuration value
`reset`	Reset to default configuration

Examples:

# Show all config
tif1 config show

# Set lib
tif1 config set lib polars

# Get cache directory
tif1 config get cache_dir

# Reset to defaults
tif1 config reset

Output Formats

Most commands support multiple output formats.

JSON

tif1 laps 2025 "Monaco" "Race" --driver VER --export laps.json

CSV

tif1 laps 2025 "Monaco" "Race" --export laps.csv

Parquet

tif1 laps 2025 "Monaco" "Race" --export laps.parquet

Piping and Scripting

The CLI is designed to work well in shell scripts.

# Get all 2025 events and process
tif1 events 2025 --json | jq '.[] | .name'

# Export laps for all drivers
for driver in VER HAM LEC; do
  tif1 laps 2025 "Monaco" "Race" --driver $driver --export "${driver}_laps.csv"
done

# Check if data exists before processing
if tif1 sessions 2025 "Monaco" | grep -q "Race"; then
  echo "Race data available"
  tif1 laps 2025 "Monaco" "Race" --export race_data.csv
fi

Environment Variables

The CLI respects all tif1 environment variables.

# Use polars lib
export TIF1_LIB=polars
tif1 laps 2025 "Monaco" "Race"

# Disable cache
export TIF1_CACHE_ENABLED=false
tif1 laps 2025 "Monaco" "Race"

# Enable debug logging
export TIF1_LOG_LEVEL=DEBUG
tif1 laps 2025 "Monaco" "Race"

Shell Completion

Enable tab completion in the shell.

Bash
Zsh
Fish

eval "$(_TIF1_COMPLETE=bash_source tif1)" >> ~/.bashrc

eval "$(_TIF1_COMPLETE=zsh_source tif1)" >> ~/.zshrc

_TIF1_COMPLETE=fish_source tif1 > ~/.config/fish/completions/tif1.fish

Error Handling

The CLI provides clear error messages and exit codes.

Exit Code	Meaning
`0`	Success
`1`	General error
`2`	Data not found
`3`	Network error
`4`	Invalid arguments

# Check exit code
tif1 laps 2025 "InvalidGP" "Race"
echo $?  # Will be 2 (data not found)

Best Practices

Use Quotes

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

Export Large Data

Use --export instead of printing large datasets to the terminal.

Enable Caching

Keep the cache enabled for repeated queries.

Check Availability

Use events and sessions to verify that data exists first.

Get Started

Guides

Concepts

Reference

CLI Commands

Installation

Global Options

Commands

events

sessions

laps

telemetry

drivers

weather

compare

cache

config

Output Formats

JSON

CSV

Parquet

Piping and Scripting

Environment Variables

Shell Completion

Error Handling

Best Practices

Use Quotes

Export Large Data

Enable Caching

Check Availability

​Installation

​Global Options

​Commands

​events

​sessions

​laps

​telemetry

​drivers

​weather

​compare

​cache

​config

​Output Formats

​JSON

​CSV

​Parquet

​Piping and Scripting

​Environment Variables

​Shell Completion

​Error Handling

​Best Practices

Use Quotes

Export Large Data

Enable Caching

Check Availability

Installation

Global Options

Commands

events

sessions

laps

telemetry

drivers

weather

compare

cache

config

Output Formats

JSON

CSV

Parquet

Piping and Scripting

Environment Variables

Shell Completion

Error Handling

Best Practices