Authentication

Flux-CLI authenticates with your LLM provider using an API key. The default provider is OpenRouter, which provides access to 200+ models through a single API.

Getting an API Key

OpenRouter (Recommended)

1. Visit OpenRouter
2. Sign up for a free account
3. Navigate to the API Keys section
4. Create a new key (free tier available for many models)

Other Providers

Flux-CLI supports any OpenAI-compatible API provider:

Configuration Methods

Method 1: Environment Variable (Recommended)

API_KEY=sk-or-v1-your-key-here
BASE_URL=https://openrouter.ai/api/v1

Method 2: Configuration Wizard

Run the interactive setup wizard:

python main.py config

The wizard will prompt you for:

1. API Key — Your provider API key
2. Base URL — The API endpoint URL (defaults to OpenRouter)
3. Model ID — The default model to use

Method 3: TOML Config File

api_key = "sk-or-v1-your-key-here"
base_url = "https://openrouter.ai/api/v1"

[model]
name = "nvidia/nemotron-3-super-120b-a12b"

How It Works

The authentication flow:

1. Load dotenv — main.py calls dotenv.load_dotenv() to load .env
2. Check config — If api_key is in the TOML config, it's exported to the environment
3. Lazy client init — The LLMClient creates the AsyncOpenAI client lazily when first needed
4. API call — The API key is passed to the OpenAI client via the environment variable

# From client/llm_client.py
class LLMClient:
  def get_client(self) -> AsyncOpenAI:
      if self._client is None:
          api_key = os.getenv("API_KEY")
          self._client = AsyncOpenAI(
              api_key=api_key,
              base_url=self.config.base_url,
              timeout=120.0,
          )
      return self._client

Common Issues

"No API key found" Error

This means the API_KEY environment variable is not set. Ensure:

1. Your .env file exists with API_KEY=your-key
2. The .env file is in the directory where you run Flux-CLI
3. You've reloaded the shell after adding the env var

"401 Unauthorized" Error

Your API key is either invalid or expired. Check:

1. The key is still active on your provider's dashboard
2. You haven't exceeded your rate limit
3. The key has the necessary permissions