How to Override CodeWhale Provider and Model Using Environment Variables

Set CODEWHALE_PROVIDER and CODEWHALE_MODEL (or their legacy aliases DEEPSEEK_PROVIDER and DEEPSEEK_MODEL) before invoking the binary to dynamically switch LLM backends and model selections at runtime.

CodeWhale implements a layered configuration system that prioritizes runtime environment variables over static configuration files. When you need to override CodeWhale provider and model using environment variables, the application resolves these values in crates/config/src/lib.rs using the codewhale_env_var helper, ensuring that your shell-level settings take precedence over ~/.codewhale/tui.toml.

Configuration Precedence Hierarchy

CodeWhale resolves provider and model settings through three distinct layers, with each layer capable of overriding the previous:

1. User configuration file (~/.codewhale/tui.toml or config.example.toml) provides baseline values.
2. Runtime environment variables (CODEWHALE_PROVIDER, CODEWHALE_MODEL and their legacy counterparts) override configuration file values.
3. CLI flags (--provider, --model) function as thin wrappers that set environment variables for the process, granting them ultimate precedence.

According to the source code in crates/config/src/lib.rs, the resolution logic explicitly checks the preferred variable first, falling back to legacy aliases only if the primary name is unset:

std::env::var("CODEWHALE_PROVIDER")
    .or_else(|_| std::env::var("DEEPSEEK_PROVIDER"))

If both new-style and legacy variables exist simultaneously, the CODEWHALE_* variant wins, as documented in docs/PROVIDERS.md.

Supported Environment Variable Names

CodeWhale recognizes two naming conventions to maintain backward compatibility while transitioning to the new branding:

• CODEWHALE_PROVIDER (preferred) / DEEPSEEK_PROVIDER (legacy)
• CODEWHALE_MODEL (preferred) / DEEPSEEK_MODEL (legacy)

The codewhale_env_var function in crates/config/src/lib.rs handles this dual-naming scheme automatically. When the TUI initializes, it stores the resolved provider ID in Config.provider and the model override in the corresponding model field, ensuring consistent behavior across the application stack.

Practical Override Examples

Single Command Overrides

Prefix your command to apply settings for one invocation only:

# Use NVIDIA NIM for this specific request

CODEWHALE_PROVIDER=nvidia-nim codewhale chat "Summarize the latest PR"

The legacy alias functions identically:

DEEPSEEK_PROVIDER=openrouter codewhale chat "Explain this Rust macro"

Model Selection Overrides

Force a specific model regardless of provider defaults:

# Preferred naming convention

CODEWHALE_MODEL=deepseek-v4-flash codewhale run myscript.py

# Legacy support

DEEPSEEK_MODEL=deepseek-v4-pro codewhale run myscript.py

Combined Provider and Model Configuration

Chain multiple variables to specify both backend and model:

CODEWHALE_PROVIDER=atlascloud \
CODEWHALE_MODEL=deepseek-ai/DeepSeek-V4-Pro \
codewhale chat "Write a Rust unit test"

CLI Flags as Environment Variable Wrappers

The --provider and --model flags are implemented as convenience wrappers that export the corresponding environment variables internally:

codewhale --provider openrouter --model arcee-ai/trinity-large-thinking \
          chat "Generate a project outline"

This approach sets the environment variables for the current process scope, following the same resolution path as manual exports.

Temporary Overrides in Scripts

For automation tasks requiring isolated configuration changes without polluting the parent shell environment, use a restoration pattern:

#!/usr/bin/env bash

# Save current values

prev_provider=$(printenv CODEWHALE_PROVIDER)
prev_model=$(printenv CODEWHALE_MODEL)

# Apply temporary overrides

export CODEWHALE_PROVIDER=fireworks
export CODEWHALE_MODEL=accounts/fireworks/models/deepseek-v4-pro

# Execute CodeWhale

codewhale chat "Explain the impact of this commit"

# Restore original environment

[[ -n $prev_provider ]] && export CODEWHALE_PROVIDER=$prev_provider || unset CODEWHALE_PROVIDER
[[ -n $prev_model   ]] && export CODEWHALE_MODEL=$prev_model   || unset CODEWHALE_MODEL

TUI Implementation Details

The EnvVarGuard struct in crates/tui/src/config.rs manages per-process environment isolation. This guard temporarily removes CODEWHALE_PROVIDER and CODEWHALE_MODEL from the environment before the TUI starts when specific override conditions are met, guaranteeing that a single run can be forced to different settings without persisting changes to the underlying configuration.

This mechanism ensures that when you override CodeWhale provider and model using environment variables, those overrides remain strictly temporary and do not leak into subsequent invocations or background processes.

Summary

• Primary variables: Use CODEWHALE_PROVIDER and CODEWHALE_MODEL for new implementations.
• Legacy support: DEEPSEEK_PROVIDER and DEEPSEEK_MODEL remain functional for backward compatibility.
• Precedence rules: Environment variables override ~/.codewhale/tui.toml, while CLI flags set environment variables for the process scope.
• Implementation locations: Resolution logic resides in crates/config/src/lib.rs, with TUI-specific handling in crates/tui/src/config.rs via EnvVarGuard.
• Documentation: Complete provider IDs and naming conventions are cataloged in docs/PROVIDERS.md and docs/CONFIGURATION.md.

Frequently Asked Questions

What is the difference between CODEWHALE_PROVIDER and DEEPSEEK_PROVIDER?

CODEWHALE_PROVIDER is the preferred modern naming convention, while DEEPSEEK_PROVIDER exists as a legacy alias for backward compatibility. If both variables are set simultaneously, CODEWHALE_PROVIDER takes precedence according to the resolution logic in crates/config/src/lib.rs. The codebase uses the codewhale_env_var helper function to check the preferred name first before falling back to legacy alternatives.

Do CLI flags override environment variables?

Yes. The --provider and --model CLI flags ultimately override environment variables because they function as wrappers that set CODEWHALE_PROVIDER and CODEWHALE_MODEL internally for the process scope. However, because they operate through the same environment variable mechanism, manually exporting these variables before running CodeWhale achieves identical results for the duration of that shell session.

How can I temporarily test different providers without changing my default configuration?

Use inline variable assignment for single commands (CODEWHALE_PROVIDER=openrouter codewhale chat), or implement the save-restore pattern in shell scripts to temporarily export values and then unset them after execution. The EnvVarGuard in crates/tui/src/config.rs also ensures that certain TUI operations isolate these overrides to prevent persistence across sessions.

Where does CodeWhale look for environment variable configuration?

The configuration loader in crates/config/src/lib.rs reads directly from the process environment using std::env::var, checking CODEWHALE_PROVIDER and CODEWHALE_MODEL first, then falling back to DEEPSEEK_PROVIDER and DEEPSEEK_MODEL if the primary names are absent. These values populate the Config.provider field and model selection before the TUI or CLI command executes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}