How to Set Up API Keys for Kimi-CLI: Environment Variables vs. Config File

Kimi-CLI reads API credentials from the KIMI_API_KEY environment variable or the api_key field in ~/.kimi/config.toml, with environment variables always taking precedence over file-based configuration.

Setting up authentication for the MoonshotAI/kimi-cli tool requires understanding its two-tier configuration system. The CLI supports both temporary environment-based authentication for CI pipelines and persistent file-based storage for daily use. According to the source code in src/kimi_cli/config.py and src/kimi_cli/llm.py, the application uses Pydantic models to securely handle these secrets while maintaining clear precedence rules.

Configuration Sources and Precedence

Kimi-CLI implements a hierarchical configuration system where runtime environment variables override static config files.

Environment Variables (Highest Priority)

The CLI checks for KIMI_API_KEY (for Kimi services) or OPENAI_API_KEY (for OpenAI compatibility) via os.getenv calls in src/kimi_cli/llm.py around lines 289-291. When present, these values mask any stored configuration and appear in the UI as masked strings like ****** (from KIMI_API_KEY) according to the display logic in src/kimi_cli/app.py lines 722-726.

User Configuration File

The persistent configuration lives at ~/.kimi/config.toml. The Config model defined in src/kimi_cli/config.py parses this file and stores the api_key as a SecretStr for security. This file supports sectioned service definitions, allowing you to maintain separate keys for different providers.

Step-by-Step Setup Methods

Method 1: Temporary Setup via Environment Variable

For quick testing,CI/CD pipelines, or temporary overrides, export the key in your shell:

export KIMI_API_KEY="sk-your-kimi-api-key"

# For OpenAI-compatible endpoints:

# export OPENAI_API_KEY="sk-your-openai-api-key"

kimi chat "Explain quantum entanglement"

This method takes immediate effect and requires no file editing.

Method 2: Persistent Setup via Config File

Create or edit ~/.kimi/config.toml to store credentials permanently:

mkdir -p ~/.kimi
cat <<EOF > ~/.kimi/config.toml
[services.kimi]
api_key = "sk-your-kimi-api-key"

# Optional: customize the endpoint

# base_url = "https://api.kimi.ai"

EOF

The CLI reads this file on startup and injects the credentials into the provider. The SecretStr type ensures the key never appears in logs or tracebacks.

Method 3: One-Command Override

Prefix any kimi command to override the config file for a single execution:

KIMI_API_KEY="sk-override-key" kimi chat "Summarize this document"

This follows standard Unix environment variable precedence without altering your shell state.

Verifying Your Configuration

Confirm which API key is active using the built-in configuration viewer:

kimi config show

The output displays the masked API key source (e.g., ****** (from KIMI_API_KEY) if using environment variables, or from the config file otherwise), helping you debug precedence issues.

Handling Multiple Providers

Kimi-CLI supports both Kimi and OpenAI-compatible endpoints simultaneously. You can store both keys in ~/.kimi/config.toml:

[services.kimi]
api_key = "sk-kimi-key"

[services.openai]
api_key = "sk-openai-key"

However, environment variables always win. If KIMI_API_KEY is set, it overrides the [services.kimi] section; if OPENAI_API_KEY is set, it overrides the [services.openai] section.

Summary

• Environment variables (KIMI_API_KEY, OPENAI_API_KEY) take highest precedence and are read via os.getenv in src/kimi_cli/llm.py.
• Config file (~/.kimi/config.toml) provides persistent storage using Pydantic SecretStr models defined in src/kimi_cli/config.py.
• Precedence rules ensure that deliberately set environment variables mask file values, preventing accidental use of stale credentials.
• Verification via kimi config show displays masked values and their sources as implemented in src/kimi_cli/app.py.

Frequently Asked Questions

Can I use both KIMI_API_KEY and OPENAI_API_KEY at the same time?

Yes. Set both environment variables to use different providers interchangeably, or define both in ~/.kimi/config.toml under separate [services.*] sections. The CLI selects the appropriate key based on the --provider flag or configured default.

Why does my API key show as asterisks in the UI?

This is the intended security behavior. According to src/kimi_cli/app.py lines 722-726, when an environment variable overrides the config file, the UI displays ****** (from KIMI_API_KEY) to confirm the source without exposing the actual secret in terminal history or screen recordings.

Is the config file encrypted?

No, the TOML file stores the key in plain text on disk, but the application treats it as a SecretStr (defined in src/kimi_cli/config.py), meaning the value is redacted from Python tracebacks, logs, and debug output. For production environments, prefer environment variables or secret management tools that inject values at runtime.

What happens if I don't set any API key?

The Pydantic validation in src/kimi_cli/config.py will raise a validation error on startup, preventing the CLI from initializing without credentials. You must provide either the environment variable or the config file entry before running any chat commands.

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