How to Configure API Keys for Kimi-CLI: Environment Variables vs Config File

Kimi-CLI reads your API key from the KIMI_API_KEY environment variable first, then falls back to the api_key field in ~/.kimi/config.toml, with environment variables always taking precedence over file-based configuration.

The MoonshotAI/kimi-cli repository provides multiple secure methods for supplying authentication credentials to the Kimi large language model service. Whether you need temporary access for CI pipelines or persistent configuration for daily development, understanding how to configure API keys for kimi-cli ensures seamless integration with your workflow.

Configuration Sources and Precedence

Kimi-CLI implements a two-tier configuration system that prioritizes security and flexibility. According to the source code in src/kimi_cli/config.py, the application uses a Pydantic-based Config model that supports both environment variables and TOML configuration files.

Environment variables provide the highest priority override. In src/kimi_cli/llm.py (lines 289-291), the application reads KIMI_API_KEY or OPENAI_API_KEY directly via os.getenv() before checking disk-based configuration. This design ensures that sensitive credentials injected via Docker secrets, CI/CD pipelines, or shell exports mask any values stored in persistent files.

User configuration files offer persistent storage for default credentials. The CLI expects a TOML file at ~/.kimi/config.toml containing a [services.kimi] section with an api_key field. The Config model stores this value as a SecretStr to prevent accidental exposure in logs or UI outputs.

Step-by-Step Configuration Methods

Method 1: Temporary Setup via Environment Variable

For one-time usage, testing, or CI/CD environments, export the API key in your shell session. This approach requires no file creation and automatically clears when the session ends.

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

# For OpenAI-compatible endpoints:

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

kimi chat "Explain the repository structure"

When an environment variable is active, src/kimi_cli/app.py (lines 722-726) displays a masked representation (e.g., ****** (from KIMI_API_KEY)) in the interface to confirm the override is working.

Method 2: Persistent Setup via Config File

Create the user configuration directory and TOML file for permanent storage. This method avoids repetitive export commands and supports additional service-specific options like custom base URLs.

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

# Optional: override the default endpoint

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

EOF

The src/kimi_cli/config.py parser validates this structure using Pydantic models, ensuring the api_key field is handled as a secure secret throughout the application lifecycle.

Method 3: One-Off Override for Single Commands

You can prefix individual commands with the environment variable to override persistent configuration without modifying shell state:

KIMI_API_KEY="sk-temporary-override-key" kimi chat "Generate a code review"

This technique is useful when testing multiple API keys or accessing different Kimi workspaces without switching config files.

Verifying Your Configuration

To confirm which credentials the CLI is using, inspect the runtime configuration display. When the environment variable takes precedence, the interface explicitly indicates (from KIMI_API_KEY) next to the masked key value, as implemented in the UI rendering logic of src/kimi_cli/app.py.

For programmatic verification, check the effective configuration:

kimi config show

This command outputs the merged configuration, displaying ****** for any active API keys while indicating their source (environment variable versus config file).

Security Considerations

The Kimi-CLI source code implements several safeguards for credential handling:

• SecretStr masking: The api_key field in src/kimi_cli/config.py uses Pydantic's SecretStr type to prevent accidental logging of plaintext keys
• Environment precedence: The logic in src/kimi_cli/llm.py ensures that environment variables mask file-based credentials, allowing secure rotation without editing configuration files
• File permissions: While not enforced by code, storing keys in ~/.kimi/config.toml allows users to set restrictive filesystem permissions (chmod 600) separately from the application

Summary

• Environment variables (KIMI_API_KEY, OPENAI_API_KEY) take precedence and are read via os.getenv() in src/kimi_cli/llm.py
• Config file location is ~/.kimi/config.toml with a [services.kimi] section containing the api_key field
• Security: API keys are stored as SecretStr objects in src/kimi_cli/config.py and masked in UI outputs per src/kimi_cli/app.py
• Override behavior: Environment variables mask config file values, enabling secure CI/CD usage without file modifications
• Verification: Use kimi config show to confirm which credential source is active

Frequently Asked Questions

What environment variable does Kimi-CLI use for authentication?

Kimi-CLI checks for KIMI_API_KEY for MoonshotAI's Kimi service and OPENAI_API_KEY for OpenAI-compatible endpoints. These are read directly from the environment via os.getenv() in src/kimi_cli/llm.py (lines 289-291) before any file-based configuration is loaded.

Where is the Kimi-CLI configuration file located?

The default user configuration file is located at ~/.kimi/config.toml. This path is parsed by the Config class in src/kimi_cli/config.py and should contain a [services.kimi] section with your API credentials and optional endpoint settings.

Can I use multiple API keys for different providers simultaneously?

Yes. You can store a default key in ~/.kimi/config.toml while overriding specific commands with environment variables. For example, keep your production key in the config file but use KIMI_API_KEY="sk-test-key" for development work. The environment variable will always take precedence for that specific session.

How does Kimi-CLI handle API key security?

The application uses Pydantic's SecretStr type (defined in src/kimi_cli/config.py) to store API keys, which automatically masks values in logs and UI outputs. When displaying configuration in src/kimi_cli/app.py (lines 722-726), the CLI shows only asterisks (******) followed by the source indicator (e.g., "from KIMI_API_KEY") to confirm authentication without exposing credentials.

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