CLI Commands

This page documents all available commands in the tif1 CLI. Each command includes its signature, parameters, options, and usage examples.

events

List all Formula 1 events for a specific year.

Signature

tif1 events YEAR

Arguments

YEAR

int

required

Year to query (2018-current)

Examples

# List all 2024 events
tif1 events 2024

# List 2023 events
tif1 events 2023

Output

Displays a formatted table with:

Event number (1-based index)
Event name (e.g., “Bahrain Grand Prix”, “Monaco Grand Prix”)
Total event count

Example Output

         F1 Events 2024          
┏━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ # ┃ Event                   ┃
┡━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 1 │ Bahrain Grand Prix      │
│ 2 │ Saudi Arabian Grand Prix│
│ 3 │ Australian Grand Prix   │
│ 4 │ Japanese Grand Prix     │
│ 5 │ Chinese Grand Prix      │
...
└───┴─────────────────────────┘

Total: 24 events

sessions

List all sessions for a specific event.

Signature

tif1 sessions YEAR EVENT

Arguments

YEAR

int

required

Year to query (2018-current)

EVENT

str

required

Event name (e.g., “Monaco”, “Bahrain Grand Prix”)

Examples

# Standard race weekend
tif1 sessions 2024 "Monaco"

# Sprint weekend
tif1 sessions 2024 "Austria"

# Partial event name matching
tif1 sessions 2024 "bahrain"

Output

Displays a formatted table with:

Session number (1-based index)
Session name (Practice 1, Practice 2, Practice 3, Qualifying, Sprint, Sprint Qualifying, Race)

Example Output

    Monaco 2024     
┏━━━┳━━━━━━━━━━━━━┓
┃ # ┃ Session     ┃
┡━━━╇━━━━━━━━━━━━━┩
│ 1 │ Practice 1  │
│ 2 │ Practice 2  │
│ 3 │ Practice 3  │
│ 4 │ Qualifying  │
│ 5 │ Race        │
└───┴─────────────┘

drivers

List all drivers participating in a specific session.

Signature

tif1 drivers YEAR EVENT SESSION

Arguments

YEAR

int

required

Year to query (2018-current)

EVENT

str

required

Event name (e.g., “Monaco”, “Bahrain Grand Prix”)

SESSION

str

required

Session name (e.g., “Race”, “Qualifying”, “Practice 1”)

Examples

# Race drivers
tif1 drivers 2024 "Monaco" "Race"

# Qualifying participants
tif1 drivers 2024 "Bahrain" "Qualifying"

# Practice session
tif1 drivers 2024 "Silverstone" "Practice 1"

Output

Displays a formatted table with:

Driver identifier (3-letter abbreviation, e.g., VER, HAM, LEC)
Team name (e.g., Red Bull Racing, Mercedes, Ferrari)
Total driver count

Example Output

  Monaco 2024 - Race   
┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ Driver ┃ Team             ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ VER    │ Red Bull Racing  │
│ PER    │ Red Bull Racing  │
│ HAM    │ Mercedes         │
│ RUS    │ Mercedes         │
│ LEC    │ Ferrari          │
│ SAI    │ Ferrari          │
...
└────────┴──────────────────┘

Total: 20 drivers

This command loads session data, which may take 2-5 seconds on first run (or <1 second if cached).

fastest

Show fastest lap times for a session, either for all drivers or a specific driver.

Signature

tif1 fastest YEAR EVENT SESSION [OPTIONS]

Arguments

YEAR

int

required

Year to query (2018-current)

EVENT

str

required

Event name (e.g., “Monaco”, “Bahrain Grand Prix”)

SESSION

str

required

Session name (e.g., “Race”, “Qualifying”, “Practice 1”)

Options

--driver, -d

str

Filter to a specific driver (3-letter code, e.g., VER, HAM, LEC)

Examples

All Drivers

# Fastest laps from all drivers
tif1 fastest 2024 "Monaco" "Race"

# Qualifying fastest laps
tif1 fastest 2024 "Bahrain" "Qualifying"

Specific Driver

# Verstappen's fastest lap
tif1 fastest 2024 "Monaco" "Race" --driver VER

# Hamilton's fastest lap (short flag)
tif1 fastest 2024 "Silverstone" "Qualifying" -d HAM

Output (All Drivers)

Displays a formatted table sorted by lap time:

Position (fastest to slowest)
Driver identifier
Team name
Lap time in seconds (formatted to 3 decimal places)

Example Output

 Fastest Laps - Monaco 2024 - Race 
┏━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Pos ┃ Driver ┃ Team             ┃ Time     ┃
┡━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ 1   │ VER    │ Red Bull Racing  │ 74.123s  │
│ 2   │ LEC    │ Ferrari          │ 74.245s  │
│ 3   │ NOR    │ McLaren          │ 74.389s  │
│ 4   │ HAM    │ Mercedes         │ 74.456s  │
│ 5   │ SAI    │ Ferrari          │ 74.501s  │
...
└─────┴────────┴──────────────────┴──────────┘

Output (Specific Driver)

Displays a single line with:

Driver identifier
Lap time in seconds (formatted to 3 decimal places)

Example Output

tif1 fastest 2024 "Monaco" "Race" -d VER
# Output: VER fastest lap: 74.123s

If a driver has no valid laps (e.g., DNS, mechanical failure), the command will display: No valid laps for <DRIVER>

cache-info

Display information about the tif1 cache.

Signature

tif1 cache-info

Arguments

None.

Examples

tif1 cache-info

Output

Displays:

Cache location: Absolute path to the cache directory
Cache files: Number of files in the cache
Total size: Cache size in megabytes (MB)

Example Output

Cache location: /home/user/.cache/tif1
Cache files: 143
Total size: 256.34 MB

The cache location can be customized via the TIF1_CACHE_DIR environment variable or .tif1rc configuration file.

cache-clear

Clear all cached data to free disk space.

Signature

tif1 cache-clear [OPTIONS]

Arguments

None.

Options

--yes, -y

bool

Skip confirmation prompt and clear cache immediately

Examples

Interactive Mode

# Prompts for confirmation
tif1 cache-clear

Output:

Are you sure you want to clear the cache? [y/N]: y
Cache cleared successfully!

Skip Confirmation

# Clear immediately without prompt
tif1 cache-clear --yes

# Short flag
tif1 cache-clear -y

Output

Confirmed:

Cache cleared successfully!

Cancelled:

Cache clear cancelled

Clearing the cache will require re-downloading data on subsequent queries. This may increase load times temporarily.

version

Display the installed tif1 version.

Signature

tif1 version

Arguments

None.

Examples

tif1 version

Output

Displays the current version number:

tif1 version 0.1.0

debug

Load a session with debug-level logging enabled for troubleshooting.

Signature

tif1 debug YEAR EVENT SESSION

Arguments

YEAR

int

required

Year to query (2018-current)

EVENT

str

required

Event name (e.g., “Monaco”, “Bahrain Grand Prix”)

SESSION

str

required

Session name (e.g., “Race”, “Qualifying”, “Practice 1”)

Examples

# Debug session loading
tif1 debug 2024 "Monaco" "Race"

# Troubleshoot data issues
tif1 debug 2024 "Bahrain" "Qualifying"

Output

Enables DEBUG-level logging and displays:

Progress indicator for session loading
Detailed HTTP request logs
Cache hit/miss information
Data parsing steps
Session statistics (driver count, lap count)

Example Output

DEBUG: Fetching session data from CDN...
DEBUG: Cache miss for session_2024_monaco_race
DEBUG: Downloading from https://cdn.jsdelivr.net/...
DEBUG: Parsing lap data...
DEBUG: Parsing telemetry data...
DEBUG: Session loaded successfully

Session loaded successfully!
Drivers: 20
Laps: 1547

Use this command when experiencing data loading issues or to understand the data pipeline behavior.

Global Options

All commands support standard Typer global options:

—help

Display help information for any command.

tif1 --help              # Show all commands
tif1 events --help       # Show help for events command
tif1 fastest --help      # Show help for fastest command

—version

Display version (alternative to tif1 version).

tif1 --version

Exit Codes

The CLI uses standard exit codes:

0: Success
1: General error (invalid arguments, data not found, network error)
2: Invalid usage (wrong number of arguments, invalid options)

Common Patterns

Analyze a Full Race Weekend

# Step 1: Find the event
tif1 events 2024

# Step 2: Check available sessions
tif1 sessions 2024 "Monaco"

# Step 3: Analyze each session
tif1 fastest 2024 "Monaco" "Practice 1"
tif1 fastest 2024 "Monaco" "Practice 2"
tif1 fastest 2024 "Monaco" "Practice 3"
tif1 fastest 2024 "Monaco" "Qualifying"
tif1 fastest 2024 "Monaco" "Race"

Compare Driver Performance

# Get fastest laps for multiple drivers
tif1 fastest 2024 "Silverstone" "Qualifying" -d VER
tif1 fastest 2024 "Silverstone" "Qualifying" -d HAM
tif1 fastest 2024 "Silverstone" "Qualifying" -d LEC

# Or see all drivers at once
tif1 fastest 2024 "Silverstone" "Qualifying"

Cache Management Workflow

# Check current cache size
tif1 cache-info

# If cache is large, clear it
tif1 cache-clear -y

# Verify cache was cleared
tif1 cache-info

Next Steps

CLI Overview

Learn about CLI features and workflows

Python API

Use tif1 programmatically for advanced analysis

Caching

Configure cache behavior and location

Error Handling

Understand error messages and troubleshooting

Get Started

Core Concepts

Guides

Advanced

CLI

Documentation Index

​events

​Signature

​Arguments

​Examples

​Output

​Example Output

​sessions

​Signature

​Arguments

​Examples

​Output

​Example Output

​drivers

​Signature

​Arguments

​Examples

​Output

​Example Output

​fastest

​Signature

​Arguments

​Options

​Examples

​All Drivers

​Specific Driver

​Output (All Drivers)

​Example Output

​Output (Specific Driver)

​Example Output

​cache-info

​Signature

​Arguments

​Examples

​Output

​Example Output

​cache-clear

​Signature

​Arguments

​Options

​Examples

​Interactive Mode

​Skip Confirmation

​Output

​version

​Signature

​Arguments

​Examples

​Output

​debug

​Signature

​Arguments

​Examples

​Output

​Example Output

​Global Options

​—help

​—version

​Exit Codes

​Common Patterns

​Analyze a Full Race Weekend

​Compare Driver Performance

​Cache Management Workflow

​Next Steps

CLI Overview

Python API

Caching

Error Handling

Build docs developers (and LLMs) love

events

Signature

Arguments

Examples

Output

Example Output

sessions

Signature

Arguments

Examples

Output

Example Output

drivers

Signature

Arguments

Examples

Output

Example Output

fastest

Signature

Arguments

Options

Examples

All Drivers

Specific Driver

Output (All Drivers)

Example Output

Output (Specific Driver)

Example Output

cache-info

Signature

Arguments

Examples

Output

Example Output

cache-clear

Signature

Arguments

Options

Examples

Interactive Mode

Skip Confirmation

Output

version

Signature

Arguments

Examples

Output

debug

Signature

Arguments

Examples

Output

Example Output

Global Options

—help

—version

Exit Codes

Common Patterns

Analyze a Full Race Weekend

Compare Driver Performance

Cache Management Workflow

Next Steps