### Run Examples with pip and Python

Source: https://github.com/punitarani/fli/blob/main/examples/README.md

Alternative methods for running examples include installing the package first with pip, or manually installing dependencies and then executing the script.

```bash
# Option 1: Install the package first
pip install flights
python examples/basic_one_way_search.py

# Option 2: Install dependencies manually
pip install pydantic curl_cffi httpx
python examples/basic_one_way_search.py

# Option 3: Use virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install pydantic curl_cffi httpx
python examples/basic_one_way_search.py
```

--------------------------------

### MCP Server: Install and Start

Source: https://context7.com/punitarani/fli/llms.txt

Install the MCP extras for the fli library and start the STDIO or HTTP server. Configure environment defaults for currency, cabin class, and max results.

```bash
# Install with MCP extras
pip install 'flights[mcp]'
```

```bash
# Start STDIO server
fli-mcp
```

```bash
# Start HTTP server (default: 0.0.0.0:8000/mcp/)
fli-mcp-http
```

```bash
# Configure environment defaults
FLI_MCP_DEFAULT_CURRENCY=EUR \
FLI_MCP_DEFAULT_CABIN_CLASS=ECONOMY \
FLI_MCP_MAX_RESULTS=20 \
fli-mcp
```

--------------------------------

### Run Fli Python Examples Directly

Source: https://github.com/punitarani/fli/blob/main/README.md

Commands to run Fli's example scripts after installing dependencies. This is an alternative to using uv.

```bash
# Quick test - run a simple example
uv run python examples/basic_one_way_search.py
```

```bash
# Run all examples to explore different features
uv run python examples/round_trip_search.py
uv run python examples/complex_flight_search.py
uv run python examples/price_tracking.py
```

--------------------------------

### Fli Development Setup and Commands

Source: https://github.com/punitarani/fli/blob/main/README.md

Instructions for setting up the Fli development environment, including cloning the repository, installing dependencies, running tests, linting, and building documentation.

```bash
# Clone the repository
git clone https://github.com/punitarani/fli.git
cd fli
```

```bash
# Install dependencies with uv
uv sync --all-extras
```

```bash
# Run tests
uv run pytest
```

```bash
# Run linting
uv run ruff check .
uv run ruff format .
```

```bash
# Build documentation
uv run mkdocs serve
```

```bash
# Or use the Makefile for common tasks
make install-all  # Install all dependencies
make test         # Run tests
make lint         # Check code style
make format       # Format code
```

--------------------------------

### Running Search Examples Directly

Source: https://github.com/punitarani/fli/blob/main/docs/api/search.md

Alternative method to run the Python search examples by first installing dependencies with pip and then executing the script directly.

```bash
# Or install dependencies and run directly
pip install pydantic curl_cffi httpx
python examples/basic_one_way_search.py
```

--------------------------------

### Install Dependencies

Source: https://github.com/punitarani/fli/blob/main/docs/guides/quickstart.md

Install the required Python packages using pip. This is necessary before running any of the provided examples.

```bash
pip install pydantic curl_cffi httpx
```

--------------------------------

### Run Fli Examples

Source: https://github.com/punitarani/fli/blob/main/docs/index.md

Execute Fli examples using `uv run` for dependency management or by installing dependencies first and then running the Python script.

```bash
# Run with uv (recommended - handles dependencies)
uv run python examples/basic_one_way_search.py

# Or install dependencies first, then run
pip install pydantic curl_cffi httpx
python examples/basic_one_way_search.py
```

--------------------------------

### Run Fli Python Examples with uv

Source: https://github.com/punitarani/fli/blob/main/README.md

Commands to execute Fli's example scripts using the uv Python package manager. Ensure dependencies are installed.

```bash
# Run examples with uv (recommended)
uv run python examples/basic_one_way_search.py
uv run python examples/round_trip_search.py
uv run python examples/date_range_search.py
```

```bash
# Or install dependencies first, then run directly
pip install pydantic curl_cffi httpx
python examples/basic_one_way_search.py
```

--------------------------------

### Install Fli and Dependencies

Source: https://github.com/punitarani/fli/blob/main/examples/README.md

Install the main Fli library and optional dependencies for advanced examples. Use 'pip install flights' for the core library and 'pip install pandas tenacity' for extended functionality.

```bash
# Install the main library
pip install flights

# For advanced examples with optional dependencies
pip install pandas tenacity
```

--------------------------------

### Run Examples with uv

Source: https://github.com/punitarani/fli/blob/main/examples/README.md

Use the 'uv' command to run any example script. This approach automatically handles dependencies, simplifying the execution process.

```bash
# Run any example with uv (automatically handles dependencies)
uv run python examples/basic_one_way_search.py

# Or from the project root
uv run python -m examples.basic_one_way_search
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/punitarani/fli/blob/main/AGENTS.md

Installs all project dependencies, including extras. Use this command to set up the development environment.

```bash
uv sync --all-extras
```

--------------------------------

### Running Search Examples with uv

Source: https://github.com/punitarani/fli/blob/main/docs/api/search.md

Instructions for running the provided Python search examples using the uv tool. This is the recommended method for development.

```bash
# Run with uv (recommended)
uv run python examples/basic_one_way_search.py
uv run python examples/date_range_search.py
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/punitarani/fli/blob/main/CLAUDE.md

Use this command to install all project dependencies, including extras.

```bash
# Install dependencies
uv sync --all-extras
```

--------------------------------

### Run Fli Examples with UV

Source: https://github.com/punitarani/fli/blob/main/docs/guides/quickstart.md

Execute complete Fli examples using the 'uv' command for development and testing.

```bash
# Run examples with uv (recommended)
uv run python examples/basic_one_way_search.py
uv run python examples/round_trip_search.py
uv run python examples/date_range_search.py
```

--------------------------------

### Install Fli for CLI

Source: https://github.com/punitarani/fli/blob/main/docs/guides/quickstart.md

Install the Fli command-line interface using pipx.

```bash
pipx install flights
```

--------------------------------

### Install Fli CLI

Source: https://github.com/punitarani/fli/blob/main/README.md

Install the Fli CLI using pip or pipx. Pipx is recommended for CLI tools.

```bash
pip install flights
```

```bash
# Install using pipx (recommended for CLI)
pipx install flights

# Get started with CLI
fli --help
```

--------------------------------

### Preferred Fli Installation with Pipx

Source: https://github.com/punitarani/fli/blob/main/skills/fli/SKILL.md

Install pipx and then use it to install the Fli package. If pipx is already installed, skip the initial steps.

```bash
python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install flights
```

```bash
pipx install flights
```

--------------------------------

### Install Fli using pip or pipx

Source: https://github.com/punitarani/fli/blob/main/docs/index.md

Install the Fli library using pip for general use or pipx for recommended CLI usage.

```bash
pip install flights
```

```bash
pipx install flights
```

--------------------------------

### Run Basic One-Way Search Example

Source: https://github.com/punitarani/fli/blob/main/docs/guides/quickstart.md

Execute the Python script for a basic one-way flight search. Ensure dependencies are installed first.

```bash
python examples/basic_one_way_search.py
```

--------------------------------

### Install flights CLI

Source: https://github.com/punitarani/fli/blob/main/docs/guides/mcp.md

Install the flights CLI tool using pipx (recommended) or pip.

```bash
# Install with pipx (recommended)
pipx install flights

# Or with pip
pip install flights
```

--------------------------------

### Airport Selection Examples

Source: https://github.com/punitarani/fli/blob/main/examples/README.md

Demonstrates how to select airports using the Airport model. Includes examples for major US and international airports.

```python
from fli.models import Airport

# Major US airports
Airport.JFK, Airport.LAX, Airport.ORD, Airport.DFW
Airport.SFO, Airport.BOS, Airport.MIA, Airport.SEA

# International airports  
Airport.LHR, Airport.CDG, Airport.NRT, Airport.SYD
```

--------------------------------

### Start Default Fli MCP Server (STDIO)

Source: https://github.com/punitarani/fli/blob/main/skills/fli/SKILL.md

Launch the Fli MCP server using STDIO, which is the default recommendation for local assistant integration.

```bash
fli-mcp
```

--------------------------------

### Install Fli for Python

Source: https://github.com/punitarani/fli/blob/main/docs/guides/quickstart.md

Install the Fli Python package using pip.

```bash
pip install flights
```

--------------------------------

### Install fli Python Library

Source: https://context7.com/punitarani/fli/llms.txt

Install the fli library using pip. For MCP server dependencies, use the '[mcp]' extra. Pipx is recommended for CLI use.

```bash
pip install flights
```

```bash
pip install 'flights[mcp]'
```

```bash
pipx install flights
```

--------------------------------

### MCP Server Configuration Example

Source: https://github.com/punitarani/fli/blob/main/skills/fli/SKILL.md

This JSON configuration shows how to set up MCP server environment variables for Fli, including default currency, cabin class, and maximum results.

```json
{
  "mcpServers": {
    "fli": {
      "command": "fli-mcp",
      "args": [],
      "env": {
        "FLI_MCP_DEFAULT_CURRENCY": "EUR",
        "FLI_MCP_DEFAULT_CABIN_CLASS": "BUSINESS",
        "FLI_MCP_MAX_RESULTS": "10"
      }
    }
  }
}
```

--------------------------------

### Start Fli MCP Server (HTTP)

Source: https://github.com/punitarani/fli/blob/main/skills/fli/SKILL.md

Start the Fli MCP server over HTTP, defaulting to http://127.0.0.1:8000/mcp/. Clients should send 'Accept: application/json, text/event-stream'.

```bash
fli-mcp-http
```

--------------------------------

### Basic Flight Search Example

Source: https://github.com/punitarani/fli/blob/main/docs/api/search.md

Demonstrates how to search for specific flights using FlightSearchFilters. Ensure all necessary models are imported.

```python
from fli.search import SearchFlights
from fli.models import Airport, SeatType, FlightSearchFilters, FlightSegment, PassengerInfo

# Create filters
filters = FlightSearchFilters(
    passenger_info=PassengerInfo(adults=1),
    flight_segments=[
        FlightSegment(
            departure_airport=[[Airport.JFK, 0]],
            arrival_airport=[[Airport.LAX, 0]],
            travel_date="2026-06-01",
        )
    ],
    seat_type=SeatType.ECONOMY
)

# Search flights
search = SearchFlights()
results = search.search(filters)
```

--------------------------------

### Start MCP HTTP Server

Source: https://github.com/punitarani/fli/blob/main/AGENTS.md

Launches the MCP HTTP server, which serves data at http://127.0.0.1:8000/mcp/. Requires `Accept: application/json, text/event-stream` header.

```bash
uv run fli-mcp-http
```

--------------------------------

### Run MCP Server on STDIO

Source: https://github.com/punitarani/fli/blob/main/CLAUDE.md

Start the Model Context Protocol (MCP) server, which communicates over Standard Input/Output.

```bash
# MCP server
fli-mcp                     # Run MCP server on STDIO
```

--------------------------------

### Install and Run Fli MCP Server

Source: https://github.com/punitarani/fli/blob/main/README.md

Install the Fli MCP server using pipx and run it either on STDIO or over HTTP. The HTTP server is accessible at http://127.0.0.1:8000/mcp/.

```bash
pipx install flights
```

```bash
fli-mcp
```

```bash
fli-mcp-http
```

--------------------------------

### Verify Fli Installation

Source: https://github.com/punitarani/fli/blob/main/skills/fli/SKILL.md

Check if the Fli CLI commands are available after installation. If commands are not found, ensure pipx is in the PATH and restart the terminal.

```bash
fli --help
fli-mcp --help
which fli-mcp
```

```bash
python3 -m pipx ensurepath
```

--------------------------------

### Install and Run act for Local CI

Source: https://github.com/punitarani/fli/blob/main/README.md

Install the 'act' tool to run GitHub Actions locally. This allows testing CI workflows without pushing to a remote repository. Ensure you have the necessary build tools or use the Docker option for a self-contained environment.

```bash
brew install act
```

```bash
# Run CI locally (lint + tests on Python 3.10-3.13)
make ci
```

```bash
# Or run CI inside Docker (no local act installation needed)
make ci-docker
```

--------------------------------

### Run MCP Server for AI Assistants (STDIO)

Source: https://github.com/punitarani/fli/blob/main/docs/guides/quickstart.md

Start the MCP server for integration with applications like Claude Desktop, using standard input/output.

```bash
# Run on STDIO (for Claude Desktop)
fli-mcp
```

--------------------------------

### Run Fli MCP Server

Source: https://github.com/punitarani/fli/blob/main/docs/index.md

Start the Model Context Protocol (MCP) server for AI assistants, either as a standalone service or over HTTP.

```bash
fli-mcp
```

```bash
fli-mcp-http
```

--------------------------------

### Run MCP Server for AI Assistants (HTTP)

Source: https://github.com/punitarani/fli/blob/main/docs/guides/quickstart.md

Start the MCP server for web integrations, exposing an HTTP endpoint.

```bash
# Run over HTTP (for web integrations)
fli-mcp-http
```

--------------------------------

### Run MCP Server over HTTP

Source: https://github.com/punitarani/fli/blob/main/CLAUDE.md

Start the Model Context Protocol (MCP) server, configured to communicate over HTTP.

```bash
fli-mcp-http               # Run MCP server over HTTP
```

--------------------------------

### Basic Flight Search with Fli Python API

Source: https://github.com/punitarani/fli/blob/main/README.md

Example demonstrating how to set up flight search filters and execute a search using the Fli Python library. Requires importing necessary models and the SearchFlights class.

```python
from datetime import datetime, timedelta
from fli.models import (
    Airport,
    PassengerInfo,
    SeatType,
    MaxStops,
    SortBy,
    FlightSearchFilters,
    FlightSegment
)
from fli.search import SearchFlights

# Create search filters
filters = FlightSearchFilters(
    passenger_info=PassengerInfo(adults=1),
    flight_segments=[
        FlightSegment(
            departure_airport=[[Airport.JFK, 0]],
            arrival_airport=[[Airport.LAX, 0]],
            travel_date=(datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d"),
        )
    ],
    seat_type=SeatType.ECONOMY,
    stops=MaxStops.NON_STOP,
    sort_by=SortBy.CHEAPEST,
)

# Search flights
search = SearchFlights()
flights = search.search(filters)

# Process results
for flight in flights:
    print(f"💰 Price: ${flight.price}")
    print(f"⏱️ Duration: {flight.duration} minutes")
    print(f"✈️ Stops: {flight.stops}")

    for leg in flight.legs:
        print(f"\n🛫 Flight: {leg.airline.value} {leg.flight_number}")
        print(f"📍 From: {leg.departure_airport.value} at {leg.departure_datetime}")
        print(f"📍 To: {leg.arrival_airport.value} at {leg.arrival_datetime}")
```

--------------------------------

### Date Range Flight Search Example

Source: https://github.com/punitarani/fli/blob/main/docs/api/search.md

Shows how to find the cheapest dates to fly within a specified range using DateSearchFilters. Requires importing SearchDates and relevant models.

```python
from fli.search import SearchDates
from fli.models import DateSearchFilters, Airport, FlightSegment, PassengerInfo

# Create filters
filters = DateSearchFilters(
    passenger_info=PassengerInfo(adults=1),
    flight_segments=[
        FlightSegment(
            departure_airport=[[Airport.JFK, 0]],
            arrival_airport=[[Airport.LAX, 0]],
            travel_date="2026-06-01",
        )
    ],
    from_date="2026-06-01",
    to_date="2026-06-30"
)

# Search dates
search = SearchDates()
results = search.search(filters)
```

--------------------------------

### Check Python Version

Source: https://github.com/punitarani/fli/blob/main/skills/fli/SKILL.md

Verify that your Python installation meets Fli's requirement of Python 3.10 or newer.

```bash
python3 --version
```

--------------------------------

### Example MCP Response for `search_dates`

Source: https://github.com/punitarani/fli/blob/main/docs/guides/mcp.md

This JSON structure represents a successful response from the `search_dates` function, detailing flight prices and dates.

```json
{
  "success": true,
  "dates": [
    {
      "date": "2026-03-15",
      "price": 350.00,
      "currency": "USD",
      "return_date": null
    },
    {
      "date": "2026-03-18",
      "price": 375.00,
      "currency": "USD",
      "return_date": null
    }
  ],
  "count": 30,
  "trip_type": "ONE_WAY",
  "date_range": "2026-03-01 to 2026-03-31"
}
```

--------------------------------

### Flight Search with Time Restrictions

Source: https://github.com/punitarani/fli/blob/main/docs/examples/advanced.md

This example demonstrates how to filter flight searches based on specific departure and arrival time windows. It requires importing TimeRestrictions and other relevant models from fli.models.

```python
from fli.models import (
    TimeRestrictions, Airport, TripType, 
    FlightSearchFilters, FlightSegment, PassengerInfo
)
from fli.search import SearchFlights

# Create filters with time restrictions
filters = FlightSearchFilters(
    trip_type=TripType.ONE_WAY,
    passenger_info=PassengerInfo(adults=1),
    flight_segments=[
        FlightSegment(
            departure_airport=[[Airport.JFK, 0]],
            arrival_airport=[[Airport.LAX, 0]],
            travel_date="2026-06-01",
            time_restrictions=TimeRestrictions(
                earliest_departure=6,  # 6 AM
                latest_departure=10,  # 10 AM
                earliest_arrival=12,  # 12 PM
                latest_arrival=18  # 6 PM
            )
        )
    ]
)

search = SearchFlights()
results = search.search(filters)
```

--------------------------------

### Complex Round Trip Search with Validations

Source: https://github.com/punitarani/fli/blob/main/docs/examples/advanced.md

Perform a complex round-trip flight search with detailed validations and specific requirements. This example demonstrates setting up flight segments with time restrictions, validating dates, and applying multiple filters such as passenger count, preferred airlines, maximum stops, and layover preferences.

```python
from fli.models import (
    Airport, Airline, SeatType, MaxStops,
    PassengerInfo, TimeRestrictions, TripType,
    FlightSegment, FlightSearchFilters, LayoverRestrictions
)
from fli.search import SearchFlights
from datetime import datetime, timedelta

# Create flight segments with time restrictions
outbound = FlightSegment(
    departure_airport=[[Airport.JFK, 0]],
    arrival_airport=[[Airport.LHR, 0]],
    travel_date="2026-06-01",
    time_restrictions=TimeRestrictions(
        earliest_departure=6,  # 6 AM
        latest_departure=12,   # 12 PM
        earliest_arrival=18,   # 6 PM
        latest_arrival=23      # 11 PM
    )
)

return_flight = FlightSegment(
    departure_airport=[[Airport.LHR, 0]],
    arrival_airport=[[Airport.JFK, 0]],
    travel_date="2026-06-15",
    time_restrictions=TimeRestrictions(
        earliest_departure=14,  # 2 PM
        latest_departure=20,    # 8 PM
        earliest_arrival=17,    # 5 PM
        latest_arrival=23       # 11 PM
    )
)

# Validate dates
today = datetime.now().date()
outbound_date = datetime.strptime(outbound.travel_date, "%Y-%m-%d").date()
return_date = datetime.strptime(return_flight.travel_date, "%Y-%m-%d").date()

if outbound_date <= today:
    raise ValueError("Outbound date must be in the future")
if return_date <= outbound_date:
    raise ValueError("Return date must be after outbound date")
if return_date - outbound_date > timedelta(days=30):
    raise ValueError("Trip duration cannot exceed 30 days")

# Create filters with complex requirements
filters = FlightSearchFilters(
    trip_type=TripType.ROUND_TRIP,
    passenger_info=PassengerInfo(
        adults=2,
        children=1,
        infants_on_lap=1
    ),
    flight_segments=[outbound, return_flight],
    stops=MaxStops.ONE_STOP_OR_FEWER,
    seat_type=SeatType.BUSINESS,
    airlines=[Airline.BA, Airline.VS],  # British Airways and Virgin Atlantic
    max_duration=720,  # 12 hours max flight time
    layover_restrictions=LayoverRestrictions(
        airports=[Airport.DUB, Airport.AMS],  # Preferred layover airports
        max_duration=180  # Maximum 3-hour layover
    )
)

search = SearchFlights()
results = search.search(filters)

for outbound_result, return_result in results:
    print(f"\nOutbound Flight (${outbound_result.price}):")
    for leg in outbound_result.legs:
        print(f"  Flight: {leg.airline.value} {leg.flight_number}")
        print(f"  From: {leg.departure_airport.value} at {leg.departure_datetime}")
        print(f"  To: {leg.arrival_airport.value} at {leg.arrival_datetime}")
        print(f"  Duration: {leg.duration} minutes")

    print(f"\nReturn Flight:")
    for leg in return_result.legs:
        print(f"  Flight: {leg.airline.value} {leg.flight_number}")
        print(f"  From: {leg.departure_airport.value} at {leg.departure_datetime}")
        print(f"  To: {leg.arrival_airport.value} at {leg.arrival_datetime}")
        print(f"  Duration: {leg.duration} minutes")
```

--------------------------------

### Serve MkDocs Locally

Source: https://github.com/punitarani/fli/blob/main/CLAUDE.md

Serve the MkDocs documentation locally for development and preview.

```bash
uv run mkdocs serve         # Serve docs locally
```

--------------------------------

### Configure Passenger Information in Python

Source: https://github.com/punitarani/fli/blob/main/examples/README.md

Demonstrates how to create PassengerInfo objects for single travelers and families with children and infants.

```python
from fli.models import PassengerInfo

# Single traveler
PassengerInfo(adults=1)

# Family with children
PassengerInfo(adults=2, children=2, infants_on_lap=1)
```

--------------------------------

### Build MkDocs Documentation

Source: https://github.com/punitarani/fli/blob/main/CLAUDE.md

Build the MkDocs documentation for the project.

```bash
# Documentation
make docs                   # Build MkDocs documentation
```

--------------------------------

### Ensure Fli/MCP Path

Source: https://github.com/punitarani/fli/blob/main/skills/fli/SKILL.md

Run this command if `fli` or `fli-mcp` commands are not found after installation. It ensures that executables installed by pipx are in your system's PATH.

```bash
python3 -m pipx ensurepath
```

--------------------------------

### Example MCP Flight Search Response

Source: https://github.com/punitarani/fli/blob/main/docs/guides/mcp.md

This is an example of a successful response from the MCP flight search tool, detailing flight prices, legs, and trip type.

```json
{
  "success": true,
  "flights": [
    {
      "price": 450.00,
      "currency": "USD",
      "legs": [
        {
          "departure_airport": "JFK",
          "arrival_airport": "LHR",
          "departure_time": "2026-03-15T18:00:00",
          "arrival_time": "2026-03-16T06:30:00",
          "duration": 450,
          "airline": "BA",
          "flight_number": "BA178"
        }
      ]
    }
  ],
  "count": 5,
  "trip_type": "ONE_WAY"
}
```

--------------------------------

### Run Standard Test Suite

Source: https://github.com/punitarani/fli/blob/main/CLAUDE.md

Execute the standard test suite for the project.

```bash
# Run tests (use these specific commands)
make test                    # Standard test suite
```

--------------------------------

### Validate Date Ranges for Round Trips

Source: https://github.com/punitarani/fli/blob/main/docs/examples/advanced.md

This function validates date ranges for round trip searches, ensuring the start date is in the future, the end date is after the start date, and the date range does not exceed 180 days. It also validates minimum and maximum stay durations.

```python
from fli.models import (
    DateSearchFilters, Airport, TripType,
    FlightSegment, PassengerInfo, SeatType, TimeRestrictions
)
from fli.search import SearchDates
from datetime import datetime, timedelta


def validate_dates(from_date: str, to_date: str, min_stay: int, max_stay: int):
    """Validate date ranges for round trip searches."""
    start = datetime.strptime(from_date, "%Y-%m-%d").date()
    end = datetime.strptime(to_date, "%Y-%m-%d").date()
    today = datetime.now().date()

    if start <= today:
        raise ValueError("Start date must be in the future")
    if end <= start:
        raise ValueError("End date must be after start date")
    if end - start > timedelta(days=180):
        raise ValueError("Date range cannot exceed 180 days")
    if min_stay < 1:
        raise ValueError("Minimum stay must be at least 1 day")
    if max_stay > 30:
        raise ValueError("Maximum stay cannot exceed 30 days")
    if min_stay > max_stay:
        raise ValueError("Minimum stay cannot be greater than maximum stay")


from_date = "2026-06-01"
to_date = "2026-06-30"
min_stay = 2
max_stay = 4

validate_dates(from_date, to_date, min_stay, max_stay)

stay_lengths = range(min_stay, max_stay + 1)
search = SearchDates()
weekend_trips = []

for duration in stay_lengths:
    outbound_date = from_date
    return_date = (
        datetime.strptime(outbound_date, "%Y-%m-%d") + timedelta(days=duration)
    ).strftime("%Y-%m-%d")

    flight_segments = [
        FlightSegment(
            departure_airport=[[Airport.JFK, 0]],
            arrival_airport=[[Airport.LAX, 0]],
            travel_date=outbound_date,
            time_restrictions=TimeRestrictions(
                earliest_departure=9,   # 9 AM
                latest_departure=18,    # 6 PM
            ),
        ),
        FlightSegment(
            departure_airport=[[Airport.LAX, 0]],
            arrival_airport=[[Airport.JFK, 0]],
            travel_date=return_date,
        ),
    ]

    filters = DateSearchFilters(
        trip_type=TripType.ROUND_TRIP,
        passenger_info=PassengerInfo(adults=1),
        flight_segments=flight_segments,
        from_date=from_date,
        to_date=to_date,
        duration=duration,
        seat_type=SeatType.ECONOMY,
    )

    results = search.search(filters)
    if not results:
        continue

    for trip in results:
        outbound, inbound = trip.date
        if outbound.weekday() >= 5:  # Saturday = 5, Sunday = 6
            weekend_trips.append({
                "outbound": outbound.strftime("%Y-%m-%d"),
                "return": inbound.strftime("%Y-%m-%d"),
                "duration": duration,
                "price": trip.price,
            })

weekend_trips.sort(key=lambda x: x["price"])

for trip in weekend_trips:
    print("\nWeekend Trip:")
    print(f"Outbound: {trip['outbound']} (Weekend)")
    print(f"Return: {trip['return']}")
    print(f"Duration: {trip['duration']} days")
    print(f"Total Price: ${trip['price']}")
```

--------------------------------

### Build Static MkDocs

Source: https://github.com/punitarani/fli/blob/main/CLAUDE.md

Build static HTML files for the MkDocs documentation.

```bash
uv run mkdocs build         # Build static docs
```

--------------------------------

### Run All Tests

Source: https://github.com/punitarani/fli/blob/main/CLAUDE.md

Execute all tests in the project.

```bash
make test-all               # Run all tests (pytest -vv --all)
```

--------------------------------

### Configure Fli MCP Server for Claude Desktop

Source: https://github.com/punitarani/fli/blob/main/README.md

Configure Claude Desktop to connect to the Fli MCP server by specifying the command to run the server. Replace <user> with your actual username.

```json
{
  "mcpServers": {
    "fli": {
      "command": "/Users/<user>/.local/bin/fli-mcp"
    }
  }
}
```

--------------------------------

### Run MCP Server

Source: https://github.com/punitarani/fli/blob/main/README.md

Commands to run the MCP server on STDIO, with uv for development, using make, or over HTTP.

```bash
# Run the MCP server on STDIO
fli-mcp
```

```bash
# Or with uv (for development)
uv run fli-mcp
```

```bash
# Or with make (for development)
make mcp
```

```bash
# Run the MCP server over HTTP (streamable)
fli-mcp-http  # serves at http://127.0.0.1:8000/mcp/
```

--------------------------------

### Retrieve Booking Options for a Flight

Source: https://context7.com/punitarani/fli/llms.txt

After performing a flight search, use `SearchFlights.get_booking_options()` to get vendor-specific fare links. The session token is automatically managed from the previous `search()` call. This method returns a list of `BookingOption` objects.

```python
from fli.search import SearchFlights
from fli.models import (
    Airport, FlightSearchFilters, FlightSegment, PassengerInfo,
    MaxStops, SeatType, SortBy,
)
from datetime import datetime, timedelta

filters = FlightSearchFilters(
    passenger_info=PassengerInfo(adults=1),
    flight_segments=[
        FlightSegment(
            departure_airport=[[Airport.SFO, 0]],
            arrival_airport=[[Airport.NRT, 0]],
            travel_date=(datetime.now() + timedelta(days=45)).strftime("%Y-%m-%d"),
        )
    ],
    seat_type=SeatType.ECONOMY,
    stops=MaxStops.NON_STOP,
    sort_by=SortBy.CHEAPEST,
)

search = SearchFlights()
flights = search.search(filters)

if flights:
    cheapest = flights[0]
    print(f"Selected flight price: ${cheapest.price}")

    options = search.get_booking_options(
        flight=cheapest,
        filters=filters,
        currency="USD",
    )

    for opt in options:
        direct = " (airline direct)" if opt.is_airline_direct else ""
        print(f"  {opt.vendor_name}{direct}: ${opt.price:.2f} — {opt.booking_url}")
```

--------------------------------

### Three-Leg Multi-city Search with Filters

Source: https://github.com/punitarani/fli/blob/main/README.md

Create a three-leg multi-city itinerary with filters for cabin class and number of stops.

```bash
# Three-leg multi-city trip with filters
fli multi \
    -l SEA,NRT,2026-12-26 \
    -l NRT,HKG,2026-12-30 \
    -l HKG,SEA,2027-01-05 \
    --class BUSINESS \
    --stops 0
```

--------------------------------

### Configure FlightSearchFilters for Complex Searches

Source: https://context7.com/punitarani/fli/llms.txt

Encapsulates all search parameters for flight searches, including passenger info, flight segments, trip type, seat class, and advanced options like airlines, alliances, price limits, and layover restrictions. Use `.encode()` to get the URL-encoded POST body for the Google Flights API.

```python
from fli.models import (
    Airport, Airline, Alliance,
    FlightSearchFilters, FlightSegment, PassengerInfo,
    SeatType, MaxStops, SortBy, TripType,
    PriceLimit, BagsFilter, EmissionsFilter, LayoverRestrictions,
)
from datetime import datetime, timedelta

filters = FlightSearchFilters(
    # Required
    passenger_info=PassengerInfo(adults=1, children=0, infants_on_lap=0, infants_in_seat=0),
    flight_segments=[
        FlightSegment(
            departure_airport=[[Airport.ORD, 0]],
            arrival_airport=[[Airport.CDG, 0]],
            travel_date=(datetime.now() + timedelta(days=60)).strftime("%Y-%m-%d"),
        )
    ],
    # Optional — all have defaults
    trip_type=TripType.ONE_WAY,           # ONE_WAY | ROUND_TRIP | MULTI_CITY
    seat_type=SeatType.ECONOMY,           # ECONOMY | PREMIUM_ECONOMY | BUSINESS | FIRST
    stops=MaxStops.ANY,                   # ANY | NON_STOP | ONE_STOP_OR_FEWER | TWO_OR_FEWER_STOPS
    sort_by=SortBy.BEST,                  # TOP_FLIGHTS | BEST | CHEAPEST | DEPARTURE_TIME | ...
    airlines=[Airline.AF, Airline.LH],    # include only Air France and Lufthansa
    airlines_exclude=[Airline.FR],        # exclude Ryanair
    alliances=[Alliance.STAR_ALLIANCE],   # include alliance
    alliances_exclude=[Alliance.SKYTEAM], # exclude alliance
    price_limit=PriceLimit(max_price=800),
    max_duration=900,                     # minutes
    layover_restrictions=LayoverRestrictions(
        airports=[Airport.FRA],
        min_duration=45,
        max_duration=300,
    ),
    bags=BagsFilter(checked_bags=1, carry_on=True),
    emissions=EmissionsFilter.LESS,       # ALL | LESS
    exclude_basic_economy=True,
    show_all_results=True,
)

# Inspect the wire encoding
print(filters.encode()[:80], "...")
```

--------------------------------

### CLI: Search Flights with Alliance/Exclusion/Locale Filters

Source: https://github.com/punitarani/fli/blob/main/docs/guides/quickstart.md

Refine flight searches using alliance membership, airline exclusion, layover duration, currency, language, and country filters.

```bash
fli flights JFK LHR 2026-06-01 \
    --alliance ONEWORLD \
    --exclude-airlines AA \
    --min-layover 90 --max-layover 360 \
    --currency EUR --language en-GB --country GB
```

--------------------------------

### Format Code with Ruff

Source: https://github.com/punitarani/fli/blob/main/CLAUDE.md

Format the code using ruff.

```bash
make format                 # Format code with ruff
```

--------------------------------

### MCP Server: Claude Desktop Configuration

Source: https://context7.com/punitarani/fli/llms.txt

Configure Claude Desktop to use the fli-mcp server by specifying the command path in the `claude_desktop_config.json` file.

```json
{
  "mcpServers": {
    "fli": {
      "command": "/Users/<user>/.local/bin/fli-mcp",
      "args": []
    }
  }
}
```

--------------------------------

### Build and Run Docker Devcontainer

Source: https://github.com/punitarani/fli/blob/main/README.md

Build the Docker devcontainer image and run CI commands within the container. Use this for consistent development and testing environments.

```bash
# Build the devcontainer
docker build -t fli-dev -f .devcontainer/Dockerfile .
```

```bash
# Run CI inside the container
docker run --rm fli-dev make lint test-all
```

```bash
# Or run lint and tests separately
docker run --rm fli-dev make lint
```

```bash
docker run --rm fli-dev make test-all
```

--------------------------------

### CLI: Find Cheapest Dates

Source: https://github.com/punitarani/fli/blob/main/docs/guides/quickstart.md

Identify the cheapest dates for a flight route within a specified date range using the Fli CLI.

```bash
fli dates JFK LHR --from 2026-06-01 --to 2026-06-30
```

--------------------------------

### CLI JSON Output for Agents

Source: https://github.com/punitarani/fli/blob/main/docs/index.md

Use the `--format json` flag for experimental CLI output, suitable for agents and tools like `jq`. Note that the schema may change in future releases.

```bash
fli flights JFK LHR 2026-06-01 --format json
```

```bash
fli dates JFK LHR --from 2026-06-01 --to 2026-06-30 --format json
```

--------------------------------

### Check Code Quality with Ruff

Source: https://github.com/punitarani/fli/blob/main/CLAUDE.md

Use this command to check code quality using ruff.

```bash
# Code quality
make lint                   # Check code with ruff
```

--------------------------------

### Format Code with Black

Source: https://github.com/punitarani/fli/blob/main/AGENTS.md

Applies code formatting using Black. Run this command to ensure consistent code style across the project.

```bash
make format
```

--------------------------------

### CLI: Search Flights with Filters

Source: https://github.com/punitarani/fli/blob/main/docs/guides/quickstart.md

Perform flight searches with advanced filters including departure time window, preferred airlines, cabin class, and stopovers.

```bash
fli flights JFK LHR 2026-06-01 \
    --time 6-20 \
    --airlines BA,KL \
    --class BUSINESS \
    --stops NON_STOP
```