How to Manage Multiple AI Models with kimi-cli: A Complete Configuration Guide

kimi-cli supports unlimited LLM models through declarative configuration files, CLI flags, and environment variables that resolve in a specific priority order.

The MoonshotAI/kimi-cli repository provides a flexible architecture for managing multiple AI models simultaneously. Instead of being locked to a single provider, you can declare any number of models and providers in a central configuration file and switch between them seamlessly using command-line options or environment overrides.

Understanding the Configuration Architecture

The multi-model capability rests on three core registries defined in src/kimi_cli/config.py. Understanding these structures is essential for properly configuring your environment.

The Model Registry

The Config.models dictionary stores individual model definitions as LLMModel objects. Each entry specifies the provider name, model identifier, context size limitations, and optional capabilities like image input or tool calling.

According to the source code in src/kimi_cli/config.py (lines 28-73), every model must reference a valid provider from the provider registry. This loose coupling allows you to define multiple models that use the same provider with different parameters.

The Provider Registry

The Config.providers dictionary contains LLMProvider definitions that hold API endpoints, authentication keys, and optional environment variable overrides. By separating providers from models, you can switch a model's backend simply by changing its provider reference without modifying endpoint URLs throughout your configuration.

Default Model Selection

The Config.default_model field determines which model kimi-cli uses when you run commands without explicit overrides. If this value is set, the CLI automatically selects the corresponding entry from the model registry unless superseded by higher-priority resolution methods.

Runtime Model Resolution Order

When determining which model to use for a session, kimi-cli follows a strict hierarchy implemented in src/kimi_cli/app.py (lines 14-21):

1. Environment Variable: KIMI_MODEL_NAME takes highest precedence
2. CLI Flag: --model or -m overrides the config default
3. Configuration Default: default_model from config.toml serves as the fallback

This resolution logic ensures that temporary overrides don't permanently alter your configuration while providing maximum flexibility for scripting and testing.

Additionally, src/kimi_cli/llm.py (lines 292-294) handles the environment variable injection:

if model_name := os.getenv("KIMI_MODEL_NAME"):
    model.model = model_name
    applied["KIMI_MODEL_NAME"] = model_name

The CLI flag implementation in src/kimi_cli/cli/__init__.py (lines 173-179) uses Typer to parse the --model option and passes it to KimiCLI.create.

Configuring Multiple Models in Practice

Create a config.toml file in your ~/.kimi/ directory to declare multiple providers and models. The following example configures OpenAI and Anthropic providers with distinct models:

# ~/.kimi/config.toml

default_model = "gpt-4o-mini"

[providers.openai]
type = "openai"
base_url = "https://api.openai.com/v1"
api_key = "YOUR_OPENAI_API_KEY"

[providers.anthropic]
type = "anthropic"
base_url = "https://api.anthropic.com"
api_key = "YOUR_ANTHROPIC_API_KEY"

[models.gpt-4o-mini]
provider = "openai"
model = "gpt-4o-mini"
max_context_size = 128000
capabilities = ["image_in", "tool_calls"]

[models.claude-3-sonnet]
provider = "anthropic"
model = "claude-3-sonnet-20240229"
max_context_size = 200000

This configuration defines two providers and two models, with gpt-4o-mini set as the persistent default.

Switching Between Models

Using the Default Model

When default_model is configured, invoke kimi-cli without arguments to use your preferred model automatically:

$ kimi

This command loads the model specified in Config.default_model from src/kimi_cli/config.py.

Overriding with CLI Flags

For one-off model switches, use the --model or -m flag defined in src/kimi_cli/cli/__init__.py:

$ kimi --model claude-3-sonnet

This override applies only to the current invocation and doesn't modify your configuration file.

Temporary Environment Variable Overrides

Set KIMI_MODEL_NAME to force a specific model regardless of CLI arguments or config defaults. This method takes precedence over all other selection methods according to the logic in src/kimi_cli/llm.py:

$ KIMI_MODEL_NAME=gpt-4o-mini kimi

This approach is ideal for CI/CD pipelines or temporary testing scenarios where you cannot modify config files.

Persisting Configuration Changes

To permanently change your default model without editing TOML manually, use the built-in configuration command:

$ kimi config set default_model claude-3-sonnet

This updates the default_model field in your configuration file automatically.

Summary

• Declarative Configuration: Define unlimited models and providers in ~/.kimi/config.toml using the Config.models and Config.providers registries.
• Resolution Priority: Environment variable KIMI_MODEL_NAME overrides CLI flags, which override Config.default_model.
• Flexible Switching: Use --model for temporary changes, environment variables for scripting, and kimi config set for permanent defaults.
• Source Architecture: Key logic resides in src/kimi_cli/config.py (definitions), src/kimi_cli/app.py (resolution), and src/kimi_cli/llm.py (environment handling).

Frequently Asked Questions

How many AI models can I configure in kimi-cli simultaneously?

There is no hard limit. The Config.models dictionary in src/kimi_cli/config.py accepts any number of LLMModel entries, allowing you to maintain configurations for dozens of models across multiple providers in a single file.

Why does my environment variable override the --model flag?

The resolution logic in src/kimi_cli/app.py checks KIMI_MODEL_NAME before processing CLI arguments. This design ensures that deployment-specific overrides (common in containerized environments) cannot be accidentally bypassed by command-line arguments.

Can I use the same provider configuration for multiple models?

Yes. The LLMModel configuration references providers by name, so multiple model entries can point to a single LLMProvider definition. This reduces redundancy when configuring several variants of the same API (e.g., different Claude model versions using the same Anthropic endpoint).

Where does kimi-cli store the active model information for the web UI?

The web interface retrieves the current model configuration through src/kimi_cli/web/api/config.py, which serializes the active model details including the chosen model name and provider settings for display in the browser interface.

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