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

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, 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. 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—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 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 processes command-line flags. When the KimiCLI class initializes in 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, 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:

# 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:

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

Environment variables form Layer 3, overriding the file:

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

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

$ 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 defines the Config model and load_config(); 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.

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, halting execution immediately and displaying a descriptive message indicating the file path and parsing failure details.

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