---
since: 1.1.1
---

# Configuration

## Configuration precedence

`AI_PROVIDER`, `AI_API_KEY`, `AI_BASE_URL`, and `AI_MODEL` are all mandatory — none of them has a built-in default, and gitaiflow will not run until every one resolves to a non-empty value. `GITAIFLOW_REMOTE` follows the same lookup, but stays optional.

Each is resolved in this order, and the loader never overwrites an already-set value from an earlier tier:

1. A real environment variable (exported in your shell, or a CI secret).
2. A project-local `.env`, discovered by walking upward from the current working directory to the repository root — so its exact location doesn't matter.
3. The global `~/.gitaiflow/config.env`, created empty by the installer on first install (left untouched on upgrades).

If any of the four mandatory variables is still empty after checking all three, gitaiflow fails fast and names exactly which ones are missing, rather than partway through a run.

## Variables

| Variable | Purpose |
|---|---|
| `AI_PROVIDER` | Free-form label (`gemini`, `openai`, `ollama`, `custom`, ...) — only affects display/usage-log grouping, mandatory, no default |
| `AI_BASE_URL` | Full OpenAI-compatible chat-completions base URL, mandatory, no default |
| `AI_API_KEY` | Provider API key, mandatory, no default — required even for providers (e.g. Ollama) that ignore its value |
| `AI_MODEL` | Model name, mandatory, no default |
| `AI_TEMPERATURE` | Sampling temperature |
| `AI_MAX_TOKENS` | Maximum output tokens |
| `AI_REQUEST_TIMEOUT` | HTTP timeout in seconds |
| `GITAIFLOW_REMOTE` | Optional standing fallback for which git remote to diff against, for repos where automatic upstream detection can't tell. Same three-tier lookup as above |
| `GITAIFLOW_MAX_RUNS_PER_DAY` | Optional local daily run warning |
| `GITAIFLOW_MAX_TOKENS_PER_DAY` | Optional local daily token warning |
| `GITAIFLOW_TELEMETRY` | Enables opt-in telemetry |
| `GITAIFLOW_TELEMETRY_URL` | Optional telemetry endpoint override |

## Example `.env`

```bash
# Mandatory — no built-in defaults
AI_PROVIDER=custom
AI_BASE_URL=https://openrouter.ai/api/v1
AI_API_KEY=<your-key>
AI_MODEL=openrouter/free

# Optional
AI_TEMPERATURE=0.2
AI_MAX_TOKENS=4096
AI_REQUEST_TIMEOUT=60
```

Do not commit this file.

## Provider examples

There are no provider presets anymore — every provider needs all four mandatory variables set explicitly, including Ollama (which ignores `AI_API_KEY`'s value but still needs it non-empty):

| Provider | Example `AI_BASE_URL` | Example `AI_MODEL` | `AI_API_KEY` |
|---|---|---|---|
| Gemini | `https://generativelanguage.googleapis.com/v1beta/openai` | `gemini-flash-lite-latest` | Real key |
| OpenAI | `https://api.openai.com/v1` | `gpt-4.1-mini` | Real key |
| Ollama | `http://127.0.0.1:11434/v1` | `llama3.2:3b` (must match `ollama list`) | Any non-empty value, e.g. `not-needed` |
| Custom | Your endpoint | Your model id | Real key |