# CodeWhale Configuration File Locations and Precedence: Complete Guide

> Master CodeWhale configuration file locations and precedence. Learn how CLI args, env vars, project overlays, workspace entries, and global defaults interact for optimal settings.

- Repository: [Hunter Bown/CodeWhale](https://github.com/Hmbown/CodeWhale)
- Tags: how-to-guide
- Published: 2026-06-02

---

**CodeWhale loads configuration from five hierarchical sources, with CLI arguments overriding environment variables, per-project overlays, workspace entries, and global defaults stored in `~/.codewhale/config.toml`.**

CodeWhale, the AI-powered terminal coding assistant from the `Hmbown/CodeWhale` repository, uses a cascading configuration system that merges multiple TOML files and environment variables. Understanding exactly where CodeWhale looks for settings—and which source wins when conflicts arise—is essential for managing API keys, model selections, and behavior flags across different development environments.

## Configuration File Locations

CodeWhale discovers settings by scanning six distinct sources across the filesystem. Each location serves a specific purpose, from global user defaults to directory-specific overrides.

### Global Default and Legacy Fallback

The primary global configuration resides at **`~/.codewhale/config.toml`**. This file loads automatically on startup and defines baseline settings for all workspaces.

If the modern path does not exist, CodeWhale falls back to the legacy **`~/.deepseek/config.toml`** location. This backward compatibility supports users migrating from the previous DeepSeek-branded iteration of the tool.

### CLI and Environment Overrides

Users can bypass the default discovery mechanism through two override methods:

- **`--config /path/to/file.toml`** – Supplied as a command-line argument, this path takes absolute precedence over all other sources.
- **`CODEWHALE_CONFIG_PATH`** (or the historic alias **`DEEPSEEK_CONFIG_PATH`**) – Environment variable pointing to an alternative config file. This applies after the global file loads but yields to `--config` arguments.

### Workspace and Project-Level Configuration

For granular control, CodeWhale supports scoped configurations that apply only to specific directories:

- **User-workspace entries** – Tables defined in the global file under **`[workspace."/abs/path/to/project"]`** (or the legacy `[projects."/abs/path"]` syntax). These entries activate when the current working directory matches the specified path.
- **Per-project overlay** – A **[`config.toml`](https://github.com/Hmbown/CodeWhale/blob/main/config.toml)** file located at `<workspace>/.codewhale/config.toml` (with fallback to `<workspace>/.deepseek/config.toml`). This overlay merges on top of the global configuration only when the current directory contains such a file. Use the `--no-project-config` flag to skip this layer for a single run.

## Configuration Precedence Order (Highest to Lowest)

When multiple configuration sources define the same key, CodeWhale resolves values using this strict hierarchy:

1. **CLI `--config`** – Explicit file paths specified on the command line win over every other source.
2. **`CODEWHALE_CONFIG_PATH`** – Environment variable overrides the global default file but is itself overridden by `--config`.
3. **Per-project overlay** – Values in `<workspace>/.codewhale/config.toml` merge on top of the global config when present.
4. **User-workspace entries** – Scoped tables like `[workspace."/abs/path"]` in the global file apply to matching directories. These merge before the per-project overlay, meaning a project-level `allow_shell = false` still takes precedence over a workspace entry.
5. **Global default file** – `~/.codewhale/config.toml` serves as the foundation. If absent, the legacy `~/.deepseek/config.toml` loads instead.

## How Configuration Loading Works in the Source Code

The precedence logic is implemented in [`crates/tui/src/config.rs`](https://github.com/Hmbown/CodeWhale/blob/main/crates/tui/src/config.rs) within the **`Config::load`** function (lines 1857–1900). This function orchestrates the loading sequence: reading the default file, applying environment variable overrides, then merging any per-project overlay while respecting the hierarchy described above.

```rust
// Conceptual flow from crates/tui/src/config.rs
let config = Config::load()
    .with_global_default()?
    .apply_env_override(CODEWHALE_CONFIG_PATH)?
    .merge_workspace_entries(current_dir)?
    .merge_project_overlay(current_dir)?;

```

Key supporting files include:
- **[`crates/tui/src/config_ui.rs`](https://github.com/Hmbown/CodeWhale/blob/main/crates/tui/src/config_ui.rs)** – Provides the interface for editing configuration files and managing per-project overlays.
- **[`config.example.toml`](https://github.com/Hmbown/CodeWhale/blob/main/config.example.toml)** – Reference template documenting all supported top-level keys such as `provider`, `model`, and `api_key`.
- **[`docs/CONFIGURATION.md`](https://github.com/Hmbown/CodeWhale/blob/main/docs/CONFIGURATION.md)** – Human-readable specification of location discovery and precedence rules.
- **[`docs/REBRAND.md`](https://github.com/Hmbown/CodeWhale/blob/main/docs/REBRAND.md)** – Documents the legacy `~/.deepseek` fallback behavior and migration paths.

## Practical Configuration Examples

Use these patterns to control CodeWhale's configuration resolution in daily workflows:

```bash

# Use the global config from ~/.codewhale/config.toml

codewhale chat "Explain the main() function"

# Override with an explicit configuration file

codewhale --config ./team-config.toml chat "Review this PR"

# Set configuration via environment variable

export CODEWHALE_CONFIG_PATH=$HOME/.codewhale/work-config.toml
codewhale chat "Show current model settings"

# Create a per-project overlay in repository root

echo 'provider = "openai"' > ./.codewhale/config.toml
echo 'model = "gpt-4o-mini"' >> ./.codewhale/config.toml
codewhale chat "Run with project-specific settings"

# Ignore project-level configuration for one execution

codewhale --no-project-config chat "Use global settings only"

```

## Summary

- CodeWhale searches six configuration sources, from global defaults to CLI arguments.
- **Highest precedence**: `--config` flag, followed by **`CODEWHALE_CONFIG_PATH`** environment variable.
- **Per-project overlays** in `<workspace>/.codewhale/config.toml` override global settings but yield to CLI and environment overrides.
- **User-workspace entries** in the global file provide directory-scoped configuration without creating separate files.
- Legacy **`~/.deepseek/`** paths serve as fallbacks for backward compatibility.
- The loading logic resides in **[`crates/tui/src/config.rs`](https://github.com/Hmbown/CodeWhale/blob/main/crates/tui/src/config.rs)**, specifically the `Config::load` implementation.

## Frequently Asked Questions

### Where does CodeWhale store its global configuration file?

CodeWhale stores global settings in **`~/.codewhale/config.toml`**. If this file does not exist, the application falls back to the legacy path `~/.deepseek/config.toml` to support users migrating from earlier versions.

### How do I temporarily override CodeWhale's configuration without editing files?

Set the **`CODEWHALE_CONFIG_PATH`** environment variable to point to an alternative TOML file, or use the **`--config /path/to/file.toml`** command-line argument. The CLI flag takes precedence over the environment variable.

### Can I disable the per-project configuration for a single command?

Yes. Pass the **`--no-project-config`** flag to skip loading `<workspace>/.codewhale/config.toml` for that specific invocation. This forces CodeWhale to use only global settings and workspace entries.

### What happens if both a workspace entry and a project overlay define the same key?

The **per-project overlay** wins. According to the configuration logic in [`docs/CONFIGURATION.md`](https://github.com/Hmbown/CodeWhale/blob/main/docs/CONFIGURATION.md), workspace entries in the global file merge first, then per-project overlays apply on top. This means a [`config.toml`](https://github.com/Hmbown/CodeWhale/blob/main/config.toml) file in your project directory can override settings defined in `[workspace."/abs/path"]` tables.