# How to Configure kimi-cli Settings: Complete Guide to TOML Config and Environment Variables

> Learn to configure kimi-cli settings easily with our complete guide. Master TOML config files and environment variables for optimal customization. Get started now.

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

---

**kimi-cli reads settings from a TOML file at `~/.config/kimi/config.toml`—or the path specified by the `KIMI_CONFIG_DIR` environment variable—with fallback defaults defined in the `Config` Pydantic model.**

The MoonshotAI/kimi-cli repository uses a hierarchical configuration system that prioritizes environment variables, user-defined TOML files, and hardcoded defaults. All configuration handling lives in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py), which exposes utilities for loading, validating, and persisting settings across the web server, LLM client, and agent runtime.

## Configuration File Location and Environment Variables

### Default Config Directory Structure

By default, kimi-cli stores its configuration in the user's config directory following the XDG Base Directory specification. As defined in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py), the system uses:

```python
DEFAULT_CONFIG_DIR: Final[Path] = Path(os.getenv("XDG_CONFIG_HOME", Path.home() / ".config")) / "kimi"
DEFAULT_CONFIG_FILE: Final[Path] = DEFAULT_CONFIG_DIR / "config.toml"
DEFAULT_SECRETS_FILE: Final[Path] = DEFAULT_CONFIG_DIR / "secrets.toml"

```

On most Linux and macOS systems, this resolves to `~/.config/kimi/config.toml`. The `DEFAULT_CONFIG_DIR` constant ensures consistency across the codebase, while the `get_config_dir()` function (also in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py)) computes the actual path at runtime.

### Overriding Paths with KIMI_CONFIG_DIR

You can relocate the entire configuration directory by setting the `KIMI_CONFIG_DIR` environment variable:

```bash
export KIMI_CONFIG_DIR="/path/to/custom/kimi"

```

The `get_config_dir()` helper checks for this variable before falling back to the default:

```python
def get_config_dir() -> Path:
    env_dir = os.getenv(ENV_KIMI_CONFIG_DIR)  # ENV_KIMI_CONFIG_DIR = "KIMI_CONFIG_DIR"

    if env_dir:
        return Path(env_dir).expanduser().resolve()
    return DEFAULT_CONFIG_DIR

```

## Configuration File Format and Options

### Main Config File (config.toml)

The primary configuration file uses TOML format and maps directly to the `Config` Pydantic model in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py). The model defines the following fields with their defaults:

- **`log_level`**: `"INFO"` – Controls console logging verbosity
- **`telemetry`**: `true` – Enables anonymous usage collection
- **`default_port`**: `5494` – Port for the web UI server (mirrors `DEFAULT_PORT` in [`src/kimi_cli/web/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/web/app.py))
- **`unknown_context_completion_tokens`**: `32000` – Fallback token budget when the LLM doesn't report context size
- **`completion_token_safety_margin`**: `1024` – Buffer subtracted from model token limits
- **`max_flow_moves`**: `1000` – Maximum tool invocation steps per agent flow

### Secrets File (secrets.toml)

Sensitive values like API keys should reside in [`secrets.toml`](https://github.com/MoonshotAI/kimi-cli/blob/main/secrets.toml) alongside [`config.toml`](https://github.com/MoonshotAI/kimi-cli/blob/main/config.toml). The `DEFAULT_SECRETS_FILE` constant points to `~/.config/kimi/secrets.toml`, keeping credentials separate from version-controlled configuration.

### Available Configuration Fields

The `Config` class in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py) uses Pydantic for validation with `extra = "ignore"`, meaning unknown keys are silently discarded for forward compatibility:

```python
class Config(BaseModel):
    log_level: str = Field(default="INFO")
    telemetry: bool = Field(default=True)
    default_port: int = Field(default=5494)
    unknown_context_completion_tokens: int = Field(default=32_000)
    completion_token_safety_margin: int = Field(default=1_024)
    max_flow_moves: int = Field(default=1000)

```

## Programmatic Configuration Access

### Loading Configuration

The `load_config()` function in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py) reads the TOML file and returns a populated `Config` instance. If the file doesn't exist, it returns a default configuration:

```python
from kimi_cli.config import load_config

# Load from default location (~/.config/kimi/config.toml)

config = load_config()

# Or load from explicit path

config = load_config(Path("/custom/path/config.toml"))

```

The function handles parsing errors gracefully, raising `ConfigError` (defined in [`src/kimi_cli/exception.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/exception.py)) for invalid TOML or validation failures.

### Saving Configuration

To persist changes programmatically, use `save_config()`:

```python
from kimi_cli.config import Config, save_config

config = Config(
    log_level="DEBUG",
    telemetry=False,
    default_port=8080
)

save_config(config)  # Writes to ~/.config/kimi/config.toml

```

This function ensures the parent directory exists via `ensure_dir()` before writing.

### Runtime Access Pattern

The CLI entry points use `get_config()` as a convenience wrapper around `load_config()`:

```python
from kimi_cli.config import get_config

config = get_config()  # Returns merged configuration for current runtime

```

## Key Configuration Defaults Across the CLI

Beyond the main `Config` model, kimi-cli defines module-specific constants that respect the central configuration:

### Web Server Settings

In [`src/kimi_cli/web/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/web/app.py), the `DEFAULT_PORT` (5494) matches the `default_port` config field. The CORS policy defaults to `DEFAULT_ALLOWED_ORIGIN_REGEX` from [`src/kimi_cli/web/auth.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/web/auth.py), restricting origins to `localhost` and `127.0.0.1` for security.

### LLM Token Budgeting

The [`src/kimi_cli/llm.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/llm.py) file defines token budgeting defaults that align with the config model:

- **`DEFAULT_UNKNOWN_CONTEXT_COMPLETION_TOKENS`**: `32000`
- **`DEFAULT_COMPLETION_TOKEN_SAFETY_MARGIN`**: `1024`

These values synchronize with the `unknown_context_completion_tokens` and `completion_token_safety_margin` configuration fields, ensuring consistent budgeting between the LLM abstraction layer and the core agent loop in [`src/kimi_cli/soul/kimisoul.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/kimisoul.py).

### Tool Output Limits

Tool execution respects output limits defined in [`src/kimi_cli/tools/utils.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/tools/utils.py):

- **`DEFAULT_MAX_CHARS`**: `50000` – Global character limit for tool output
- **`DEFAULT_MAX_LINE_LENGTH`**: `2000` – Per-line truncation threshold

These protect against runaway output from commands like `grep` or `cat` on large files.

### Agent Flow Limits

The `KimiSoul` class in [`src/kimi_cli/soul/kimisoul.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/kimisoul.py) uses `DEFAULT_MAX_FLOW_MOVES` (1000) to prevent infinite agent loops, matching the `max_flow_moves` configuration value.

## Creating and Editing Your Configuration

Create a minimal configuration file at `~/.config/kimi/config.toml`:

```toml
log_level = "DEBUG"
telemetry = false
default_port = 5494

unknown_context_completion_tokens = 32000
completion_token_safety_margin = 1024
max_flow_moves = 1000

```

For API keys and secrets, use `~/.config/kimi/secrets.toml`:

```toml
api_key = "sk-..."

```

Changes take effect on the next CLI invocation; the configuration is loaded lazily when `get_config()` or `load_config()` is first called.

## Summary

- **kimi-cli** stores configuration in TOML format at `~/.config/kimi/config.toml` by default, or under the path specified by the `KIMI_CONFIG_DIR` environment variable.
- The `Config` Pydantic model in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py) validates fields including `log_level`, `telemetry`, `default_port`, and token budgeting parameters.
- Use `load_config()` and `save_config()` to programmatically read and write configuration, or `get_config()` for runtime access.
- Secrets should reside in `~/.config/kimi/secrets.toml`, separate from the main configuration.
- Module-specific defaults in [`src/kimi_cli/llm.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/llm.py), [`src/kimi_cli/tools/utils.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/tools/utils.py), and [`src/kimi_cli/soul/kimisoul.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/kimisoul.py) remain synchronized with the central configuration values.

## Frequently Asked Questions

### How do I change the default port for the kimi-cli web server?

Set the `default_port` field in your [`config.toml`](https://github.com/MoonshotAI/kimi-cli/blob/main/config.toml) file to your desired port number (e.g., `default_port = 8080`), or override it temporarily using the `--port` flag when running `kimi server`. The default value of `5494` is defined in both [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py) and [`src/kimi_cli/web/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/web/app.py).

### Where should I store my API keys for kimi-cli?

Store sensitive credentials in `~/.config/kimi/secrets.toml` (or `$KIMI_CONFIG_DIR/secrets.toml`). This file is referenced by the `DEFAULT_SECRETS_FILE` constant in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py) and keeps authentication tokens separate from your main configuration file, which you might commit to version control.

### What happens if my config.toml file has invalid syntax?

The `load_config()` function catches TOML parsing errors and raises a `ConfigError` (defined in [`src/kimi_cli/exception.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/exception.py)) with a descriptive message indicating the file path and specific error. If the file is missing entirely, the function returns a `Config` instance populated with hardcoded defaults rather than crashing.

### Can I disable telemetry in kimi-cli?

Yes. Set `telemetry = false` in your `~/.config/kimi/config.toml` file. The `Config` model in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py) defaults this value to `true`, but it respects your override when loading the configuration via `get_config()`.