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

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, 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, the system uses:

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

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

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

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. 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)
• 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 alongside 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 uses Pydantic for validation with extra = "ignore", meaning unknown keys are silently discarded for forward compatibility:

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 reads the TOML file and returns a populated Config instance. If the file doesn't exist, it returns a default configuration:

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) for invalid TOML or validation failures.

Saving Configuration

To persist changes programmatically, use save_config():

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():

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, 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, restricting origins to localhost and 127.0.0.1 for security.

LLM Token Budgeting

The 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.

Tool Output Limits

Tool execution respects output limits defined in 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 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:

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:

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 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, src/kimi_cli/tools/utils.py, and 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 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 and 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 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) 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 defaults this value to true, but it respects your override when loading the configuration via get_config().

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