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

> Learn to manage multiple AI models effortlessly with kimi-cli. This guide covers declarative configurations, CLI flags, and environment variables for seamless LLM integration.

- Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
- Tags: how-to-guide
- Published: 2026-07-19

---

**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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/llm.py) (lines 292-294) handles the environment variable injection:

```python
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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/config.toml) file in your `~/.kimi/` directory to declare multiple providers and models. The following example configures OpenAI and Anthropic providers with distinct models:

```toml

# ~/.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:

```bash
$ kimi

```

This command loads the model specified in `Config.default_model` from [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py):

```bash
$ 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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/llm.py):

```bash
$ 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:

```bash
$ 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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py) (definitions), [`src/kimi_cli/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/app.py) (resolution), and [`src/kimi_cli/llm.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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.