OpenQuery/docs/api/environment-variables.md

# Environment Variables

Reference for all environment variables used by OpenQuery.

## 📋 Summary

| Variable | Purpose | Required | Default | Example |
|----------|---------|----------|---------|---------|
| `OPENROUTER_API_KEY` | OpenRouter authentication | **Yes** | (none) | `sk-or-...` |
| `OPENROUTER_MODEL` | Override default LLM model | No | `qwen/qwen3.5-flash-02-23` | `google/gemini-3-flash-preview` |
| `SEARXNG_URL` | SearxNG instance URL | No | `http://localhost:8002` | `https://searx.example.com` |

## Detailed Reference

### `OPENROUTER_API_KEY`

**Purpose**: Your OpenRouter API authentication token.

**Required**: Yes, unless you have `ApiKey` set in config file.

**How to Obtain**:
1. Sign up at https://openrouter.ai
2. Go to Dashboard → API Keys
3. Copy your key (starts with `sk-or-`)

**Priority**: Overrides config file `ApiKey`.

**Setting**:

```bash
# Bash/Zsh
export OPENROUTER_API_KEY="sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Fish
set -x OPENROUTER_API_KEY "sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# PowerShell
$env:OPENROUTER_API_KEY="sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Windows CMD
set OPENROUTER_API_KEY=sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**Security**:
- Never commit API key to version control
- Don't share key publicly
- Use environment variables or config file with restrictive permissions (600)
- Rotate key if accidentally exposed

**Validation**: OpenQuery checks if key is empty string and exits with error if missing:

```
[Error] API Key is missing. Set OPENROUTER_API_KEY environment variable or run 'configure -i' to set it up.
```

### `OPENROUTER_MODEL`

**Purpose**: Override the default LLM model used for both query generation and final answer.

**Required**: No.

**Default**: `qwen/qwen3.5-flash-02-23`

**Available Models** (from OpenRouter):

| Model | Provider | Context | Cost (Input/Output per 1M tokens) |
|-------|----------|---------|-----------------------------------|
| `qwen/qwen3.5-flash-02-23` | Alibaba | 200K | \$0.10 / \$0.20 |
| `qwen/qwen3.5-122b-a10b` | Alibaba | 200K | ~\$0.20 / ~\$0.40 |
| `minimax/minimax-m2.5` | MiniMax | 200K | ~\$0.20 / ~\$0.40 |
| `google/gemini-3-flash-preview` | Google | 1M | ~\$0.10 / ~\$0.40 |
| `deepseek/deepseek-v3.2` | DeepSeek | 200K | ~\$0.10 / ~\$0.30 |
| `moonshotai/kimi-k2.5` | Moonshot AI | 200K | ~\$0.10 / ~\$0.30 |

(See OpenRouter for current pricing.)

**Setting**:

```bash
export OPENROUTER_MODEL="google/gemini-3-flash-preview"
```

**Interactive Config Models**: The `configure -i` wizard shows only these 6 models for convenience, but you can set any OpenRouter model via environment variable or non-interactive configure.

**Note**: Different models have different:
- Speed (Flash models faster)
- Cost (check pricing)
- Quality (may vary by task)
- Context window size (Gemini 3 Flash has 1M tokens, others ~200K)

### `SEARXNG_URL`

**Purpose**: URL of the SearxNG metasearch instance.

**Required**: No.

**Default**: `http://localhost:8002`

**Format**: Must include protocol (`http://` or `https://`) and host:port.

**Setting**:

```bash
# Local Docker instance
export SEARXNG_URL="http://localhost:8002"

# Remote instance with HTTPS
export SEARXNG_URL="https://searx.example.com"

# Custom port
export SEARXNG_URL="http://localhost:8080"
```

**Finding a Public Instance**:
- Visit https://searx.space for list of public instances
- Choose one with HTTPS and low latency
- Note: Public instances may have rate limits or require attribution

**Priority**: Overrides any default, but not config file (no config setting for SearxNG URL - only env var). Could be added to config in future.

**Test Your Instance**:
```bash
curl "$SEARXNG_URL/search?q=test&format=json" | head
```

Expected: JSON with `"results": [...]`.

---

## Configuration Priority Recap

When OpenQuery needs a value:

1. **Command-line option** (`--model`, `--key` from configure) - highest
2. **Environment variable** (`OPENROUTER_MODEL`, `OPENROUTER_API_KEY`, `SEARXNG_URL`)
3. **Configuration file** (`~/.config/openquery/config`: `Model`, `ApiKey`)
4. **Hard-coded default** (only for model)

**Example**:
```bash
# Config file: Model=qwen/qwen3.5-flash-02-23
export OPENROUTER_MODEL="deepseek/deepseek-v3.2"
openquery --model "google/gemini-3-flash-preview" "question"
# Uses: model=google (CLI override), overrides env and config
```

---

## Troubleshooting Environment Variables

### Variable Not Taking Effect

**Symptom**: `openquery` still uses old value after export.

**Causes**:
- Exported in different shell session
- Exported after running `openquery`
- Shell profile not reloaded

**Check**:
```bash
echo $OPENROUTER_API_KEY
# Should print the key (or blank if unset)
```

**Fix**:
```bash
# Export in current session
export OPENROUTER_API_KEY="sk-or-..."

# Or add to ~/.bashrc / ~/.zshrc and restart terminal
```

### Special Characters in Values

If your API key contains special characters (`$`, `!`, etc.), quote properly:

```bash
export OPENROUTER_API_KEY='sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
# Single quotes prevent shell expansion
```

### Variable Name Typos

`OPENROUTER_API_KEY` is all caps with underscores. `openrouter_api_key` (lowercase) won't work.

**Check spelling**:
```bash
env | grep -i openrouter
```

### Windows Environment Variables

On Windows, environment variables are set per-session or user-level:

**PowerShell** (current session):
```powershell
$env:OPENROUTER_API_KEY="sk-or-..."
```

**Persistent** (PowerShell):
```powershell
[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-...", "User")
```

**CMD**:
```cmd
set OPENROUTER_API_KEY=sk-or-...
```

**System Properties** → Advanced → Environment Variables (GUI)

---

## Next Steps

- **[Configuration File](../configuration.md)** - Persistent configuration
- **[Usage Guide](../usage.md)** - How to use these variables
- **[Troubleshooting](../troubleshooting.md)** - Diagnose environment issues

---

**Quick Reference**

```bash
# Required
export OPENROUTER_API_KEY="sk-or-..."

# Optional (override defaults)
export OPENROUTER_MODEL="google/gemini-3-flash-preview"
export SEARXNG_URL="https://searx.example.com"

# Run
openquery "your question"
```