Configuration

Git-Iris uses a two-tier configuration system: global settings for your personal preferences, and project-specific settings that teams can share without exposing secrets.

Global Configuration

Global settings live in ~/.config/git-iris/config.toml and apply to all repositories.

Set Up Your Provider

Pick your LLM provider and configure the API key:

OpenAI:

git-iris config --provider openai --api-key sk-...

Anthropic:

git-iris config --provider anthropic --api-key sk-ant-...

Google:

git-iris config --provider google --api-key AIza...

The API key is stored securely in your global config file.

Environment Variables

Prefer environment variables? Git-Iris checks these:

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=AIza...

Environment variables take precedence over config file values.

View Current Configuration

git-iris config

This displays your active provider, model, presets, and all configured providers.

Provider Details

Git-Iris supports three LLM providers with different strengths:

Provider	Default Model	Fast Model	Context Window	Best For
openai	gpt-5.4	gpt-5.4-mini	128K	General purpose, fast
anthropic	claude-opus-4-6	claude-haiku-4-5-20251001	200K	Deep analysis, code understanding
google	gemini-3-pro-preview	gemini-2.5-flash	1M	Massive context windows

Fast models are used for simple tasks like status updates and parsing. The primary model handles complex analysis.

Override Models

Set a custom model for your provider:

git-iris config --provider anthropic --model claude-opus-4-6

Set a custom fast model:

git-iris config --provider openai --fast-model gpt-5.4-mini

Token Limits

Override the default token limit:

git-iris config --provider openai --token-limit 4000

Customization Options

Gitmoji

Enable or disable emoji prefixes in commits:

git-iris config --gitmoji     # Enable
git-iris config --no-gitmoji  # Disable

Critic Verification

Git-Iris runs a critic pass after generated artifacts by default. The critic checks whether the draft is supported by repository evidence and allows one regeneration when it finds material overclaims.

The critic applies to commit messages, reviews, PR descriptions, changelogs, and release notes. It adds one extra model call, and a second extra call only when the critic asks Iris to revise the draft.

To opt out globally, run git-iris config --no-critic or set critic_enabled = false in your config file.

git-iris config --critic     # Enable
git-iris config --no-critic  # Disable

# Or disable it for one invocation
git-iris review --no-critic --print

Instruction Presets

Set a default style preset:

git-iris config --preset conventional
git-iris config --preset detailed
git-iris config --preset cosmic

List available presets:

git-iris list-presets

Presets are categorized:

• General (both commits and reviews): default, conventional, detailed, concise, cosmic
• Review-specific: security, performance, architecture, testing, maintainability

Custom Instructions

Add global instructions that apply to all operations:

git-iris config --instructions "Always include JIRA ticket numbers in brackets"

These combine with presets—your custom instructions are applied in addition to the preset style.

Additional Parameters

Set provider-specific parameters:

git-iris config --provider openai \
  --param reasoning='{"effort":"medium"}' \
  --param text='{"verbosity":"low"}'

For OpenAI reasoning models, prefer --token-limit for output-token budgets instead of manually setting legacy token params in --param.

Project Configuration

Project settings live in .irisconfig in your repository root. Teams can commit this file to share settings without exposing API keys.

Create Project Config

Set project-specific settings:

git-iris project-config --provider openai --preset conventional

Set a model for the project:

git-iris project-config --model gpt-5.4

Set project instructions:

git-iris project-config --instructions "Follow Angular commit format"

View Project Config

git-iris project-config --print

Security Note

API keys are NEVER stored in .irisconfig files. Only non-sensitive settings like models, presets, and custom instructions are saved. This prevents accidentally committing secrets to version control.

API keys must be in your global config (~/.config/git-iris/config.toml) or environment variables.

Configuration Precedence

Settings are layered with this priority:

1. CLI flags (highest priority)
2. Environment variables
3. Project config (.irisconfig)
4. Global config (~/.config/git-iris/config.toml)
5. Defaults (lowest priority)

Example:

# Project config sets anthropic, but CLI overrides for this run
git-iris gen --provider openai

Themes

Git-Iris ships with five SilkCircuit variants (silkcircuit-neon, silkcircuit-soft, silkcircuit-vibrant, silkcircuit-glow, silkcircuit-dawn) plus 34 community themes from the opaline catalog.

There is no git-iris config --theme flag. Set your default theme by editing ~/.config/git-iris/config.toml:

theme = "silkcircuit-glow"

List available themes (builtins + any installed in ~/.config/git-iris/themes/ or ~/.config/opaline/themes/):

git-iris themes

--theme is a global flag, so it works on any subcommand for a single session:

git-iris studio --theme silkcircuit-dawn
git-iris gen --theme silkcircuit-vibrant

Advanced Options

Debug Mode

Enable color-coded agent execution output:

git-iris gen --debug

This shows Iris's tool calls, reasoning, and token usage in real-time with gorgeous formatting.

Logging

Log debug messages to a file:

git-iris gen --log

Custom log file path:

git-iris gen --log --log-file /tmp/iris-debug.log

Quiet Mode

Suppress spinners and progress messages:

git-iris gen --quiet

Useful for scripting and CI/CD where you only want final output.

Example Workflows

Team Setup

Commit shared project settings:

git-iris project-config --provider openai --preset conventional
git add .irisconfig
git commit -m "Add Git-Iris project configuration"

Team members clone the repo and only need to set their personal API key:

git-iris config --provider openai --api-key sk-...

Multiple Providers

Switch providers easily:

git-iris config --provider openai --api-key sk-...
git-iris config --provider anthropic --api-key sk-ant-...

# Use OpenAI for this commit
git-iris gen --provider openai

# Use Anthropic for reviews
git-iris review --provider anthropic

# Use Google for large release notes
git-iris release-notes --provider google --from v1.0.0

Per-Repository Presets

Different projects can use different styles:

cd backend-api
git-iris project-config --preset conventional

cd frontend-app
git-iris project-config --preset detailed

Configuration File Format

The global config file (~/.config/git-iris/config.toml) looks like this:

default_provider = "openai"
use_gitmoji = true
critic_enabled = true
instruction_preset = "conventional"
instructions = "Always include ticket numbers"
theme = "silkcircuit-neon"

[providers.openai]
api_key = "sk-..."
model = "gpt-5.4"
fast_model = "gpt-5.4-mini"

[providers.anthropic]
api_key = "sk-ant-..."
model = "claude-opus-4-6"
fast_model = "claude-haiku-4-5-20251001"

[providers.google]
api_key = "AIza..."
model = "gemini-3-pro-preview"
fast_model = "gemini-2.5-flash"

You can edit this manually if you prefer, but the git-iris config command is safer.

What's Next?

With configuration complete, explore Git-Iris features:

• User Guide: Commits — Master AI-generated commit messages
• User Guide: Reviews — Get detailed code reviews
• Iris Studio — Learn all six Studio modes

Press Shift+S in Studio to adjust settings without leaving the interface.