Quick Start

This guide walks you through setting up llm-discovery and running your first commands.

Zero Configuration Quick Start

Try llm-discovery instantly without any API keys using prebuilt model data (updated daily):

# Display models using prebuilt data (no API keys required)
$ uvx llm-discovery list

Expected output:

Provider       Model ID              Model Name
─────────────────────────────────────────────────
OpenAI         gpt-4                 GPT-4
OpenAI         gpt-3.5-turbo         GPT-3.5 Turbo
Google         gemini-pro            Gemini Pro
Anthropic      claude-3-opus         Claude 3 Opus

Total models: 42

Data Source: PREBUILT
Last Updated: 2025-10-19 00:00 UTC
Age: 10.5 hours

The data source information shows:

Data Source: Whether data comes from API (real-time) or PREBUILT (daily snapshot)
Last Updated: When the data was generated
Age: How old the data is in hours

Note

Prebuilt data is automatically updated daily at 00:00 UTC via GitHub Actions. Maximum data age is 24 hours. For real-time data, configure API keys (see below).

Warning

If data is older than 24 hours, a yellow warning will appear. If data is older than 7 days, a red warning will appear with a recommendation to run update.

Environment Variables (For Real-time Data)

Set up API keys for the LLM providers you want to monitor.

OpenAI

export OPENAI_API_KEY="sk-..."

Google AI Studio

export GOOGLE_API_KEY="AIza..."

Google Vertex AI

As an alternative to Google AI Studio, you can use Vertex AI:

export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/gcp-credentials.json"

Warning

Never commit API keys to version control. Store them securely using environment variables or secret management tools.

Note

You can configure any combination of providers. llm-discovery will fetch models from all providers with configured credentials.

Basic Commands

Update: Fetch and Cache Models

Fetch the latest model data from all configured providers:

$ uvx llm-discovery update

Expected output:

OpenAI: 15, Google: 20, Anthropic: 7 / Total: 42 / Cached to: ~/.cache/llm-discovery/models_cache.toml

Tip

Use uvx to run llm-discovery without installation. This ensures you always use the latest version.

List: Display Cached Models

Display models in a formatted table:

$ uvx llm-discovery list

Expected output:

Provider       Model ID              Model Name
─────────────────────────────────────────────────
OpenAI         gpt-4                 GPT-4
OpenAI         gpt-3.5-turbo         GPT-3.5 Turbo
Google         gemini-pro            Gemini Pro
Anthropic      claude-3-opus         Claude 3 Opus

Export: Save Model Data

Export model data in various formats:

# Export to JSON
$ uvx llm-discovery export --format json --output models.json

# Export to CSV
$ uvx llm-discovery export --format csv --output models.csv

# Export to YAML
$ uvx llm-discovery export --format yaml --output models.yaml

# Export to Markdown
$ uvx llm-discovery export --format markdown --output models.md

# Export to TOML
$ uvx llm-discovery export --format toml --output models.toml

Data Source Metadata in Exports:

All export formats include data source information:

JSON: metadata.data_source, metadata.source_timestamp, metadata.data_age_hours
CSV: data_source and source_timestamp columns
Markdown: “Data Source” section header
YAML/TOML: Standard model data (no additional metadata)

Example JSON export with data source info:

{
  "metadata": {
    "version": "1.0",
    "generated_at": "2025-10-19T10:30:00Z",
    "total_models": 42,
    "providers": ["openai", "google", "anthropic"],
    "data_source": "prebuilt",
    "source_timestamp": "2025-10-19T00:00:00Z",
    "data_age_hours": 10.5
  },
  "models": {
    "openai": [...],
    "google": [...],
    "anthropic": [...]
  }
}

Python API Basic Usage

Use llm-discovery as a library in your Python applications.

Fetch All Models

import asyncio
from llm_discovery import DiscoveryClient
from llm_discovery.models.config import Config

async def main():
    # Load configuration from environment variables
    config = Config.from_env()
    client = DiscoveryClient(config)

    # Fetch models from all providers
    provider_snapshots = await client.fetch_all_models()

    # Display all models
    for provider in provider_snapshots:
        print(f"\nProvider: {provider.provider_name}")
        print(f"Total models: {len(provider.models)}")
        for model in provider.models:
            print(f"  - {model.model_id}: {model.model_name}")

asyncio.run(main())

Filter Models by Provider

import asyncio
from llm_discovery import DiscoveryClient
from llm_discovery.models.config import Config

async def main():
    config = Config.from_env()
    client = DiscoveryClient(config)

    # Fetch all models
    provider_snapshots = await client.fetch_all_models()

    # Filter OpenAI models only
    openai_models = [
        model for snapshot in provider_snapshots
        if snapshot.provider_name == "openai"
        for model in snapshot.models
    ]

    print(f"OpenAI models: {len(openai_models)}")
    for model in openai_models:
        print(f"  - {model.model_id}")

asyncio.run(main())

Tip

The Python API uses async/await for efficient concurrent fetching from multiple providers. Always use asyncio.run() or run within an existing async context.

Offline Mode

llm-discovery operates in cache-first mode, allowing offline usage after initial data fetch.

# Fetch data while online
$ uvx llm-discovery update

# Use cached data offline (no internet required)
$ uvx llm-discovery list
$ uvx llm-discovery export --format json --output models.json

Cache location: ~/.cache/llm-discovery/models_cache.toml

Change Detection

Track model additions and removals over time:

$ uvx llm-discovery update --detect-changes

Expected output when changes detected:

Added models (3): openai/gpt-4.5, google/gemini-2.0, anthropic/claude-3.5-opus
Removed models (1): openai/gpt-3.5-turbo-0301

Changes are recorded in:

~/.cache/llm-discovery/changes.json
~/.cache/llm-discovery/CHANGELOG.md

Next Steps

For more detailed documentation:

API Reference: See technical contract at specs/001-llm-model-discovery/contracts/python-api.md
CLI Reference: See technical contract at specs/001-llm-model-discovery/contracts/cli-interface.md
Contributing: See CONTRIBUTING.md in the repository root for development guidelines