# Kimi CLI Configuration Loading Precedence: Environment Variables, Config Files, and CLI Overrides

> Understand Kimi CLI configuration loading precedence. Discover how CLI flags, environment variables, and config files override default settings for seamless customization.

- Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
- Tags: internals
- Published: 2026-07-20

---

**Kimi CLI applies a four-tier hierarchy where command-line flags take precedence over environment variables, which override TOML configuration files, which finally supersede hard-coded defaults defined in the source code.**

The MoonshotAI/kimi-cli repository implements a layered configuration system that allows users to customize behavior through multiple channels. Understanding the exact configuration loading precedence is essential for debugging unexpected behavior and managing deployment environments. This article examines the source code to reveal how settings from defaults, files, environment variables, and CLI arguments merge into the final runtime configuration.

## The Configuration Precedence Hierarchy

The loading order follows a predictable cascade from lowest to highest priority. According to the implementation in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py), the system evaluates sources in the following sequence:

### 1. Built-in Defaults (Lowest Priority)

The foundation layer resides in the **Config** data model defined in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py). These hard-coded values ensure the application has sensible fallbacks for every setting before any user customization is applied.

### 2. User Configuration File

If present, a **TOML** file at `~/.kimi/config.toml` (or a custom path specified via `--config`) loads next. The `load_config()` function parses this file and overlays its values onto the defaults, selectively replacing only the keys that appear in the file.

### 3. Environment Variables

Any variable prefixed with **`KIMI_`** (such as `KIMI_MODEL` or `KIMI_API_KEY`) is read via `os.getenv` and injected into the configuration. These values overwrite settings from both the defaults and the TOML file, making them ideal for CI/CD pipelines and secret management.

### 4. CLI Arguments (Highest Priority)

Finally, arguments passed directly to the `kimi` command—parsed by Typer in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py)—override all previous layers. This ensures that explicit user input always wins.

## Technical Implementation Details

The merging logic lives primarily in two locations. The `load_config()` function in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py) orchestrates the initial three layers by first instantiating the default **Config** model, then conditionally parsing the TOML file, and finally scanning for environment variables.

After this base configuration is assembled, the Typer application defined in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) processes command-line flags. When the **KimiCLI** class initializes in [`src/kimi_cli/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/app.py), it receives the fully merged configuration object, with CLI values already applied as the final override.

Error handling throughout this process utilizes `ConfigError` exceptions defined in [`src/kimi_cli/exception.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/exception.py), which triggers when the TOML file is malformed or required variables are missing.

## Configuration Loading in Practice

The following examples demonstrate how higher-priority sources override lower ones in practice:

```bash

# Layer 1: Defaults only (no config file, no env vars)

$ kimi chat "Hello"

```

Create a TOML file at `~/.kimi/config.toml` to establish Layer 2:

```toml
[profile]
model = "kimi-k2-chat"
api_key = "toml-key-12345"

```

Environment variables form Layer 3, overriding the file:

```bash
export KIMI_MODEL="kimi-latest"
export KIMI_API_KEY="env-key-67890"
$ kimi chat "Hello"

```

Command-line flags constitute Layer 4, taking ultimate precedence:

```bash
$ kimi --model="kimi-k2-32k" --api-key="cli-key-00000" chat "Hello"

```

## Summary

- **Default hierarchy**: CLI arguments > Environment variables (`KIMI_*`) > TOML config file (`~/.kimi/config.toml`) > Built-in defaults.
- **Core implementation**: [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py) defines the **Config** model and `load_config()`; [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) handles CLI parsing.
- **Environment prefix**: Only variables beginning with `KIMI_` are recognized and mapped to configuration keys.
- **Error handling**: Malformed files raise `ConfigError` from [`src/kimi_cli/exception.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/exception.py).

## Frequently Asked Questions

### Where does Kimi CLI look for the configuration file?

By default, Kimi CLI searches for a TOML file at `~/.kimi/config.toml`. You can specify an alternate location using the `--config` flag when invoking the CLI, which is processed before the file loading logic executes.

### What naming convention do environment variables use?

All environment variables must start with the `KIMI_` prefix. For example, `KIMI_API_KEY` maps to the `api_key` setting, and `KIMI_MODEL` maps to the model selection. The `load_config()` function strips the prefix and matches the remainder against Config model fields.

### Can I mix configuration sources?

Yes. You can define base settings in the TOML file, override specific values with environment variables for different deployment stages, and further refine behavior with CLI flags for one-off tasks. The precedence rules ensure predictable layering without ambiguity.

### What happens if the configuration file is malformed?

The system raises a `ConfigError` exception defined in [`src/kimi_cli/exception.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/exception.py), halting execution immediately and displaying a descriptive message indicating the file path and parsing failure details.