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

> Learn how to configure your Kimi-CLI API key using environment variables or the config file. Discover the precedence rules for secure and flexible access.

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

---

**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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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.

```bash
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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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.

```bash
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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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:

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

For programmatic verification, check the effective configuration:

```bash
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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py) and masked in UI outputs per [`src/kimi_cli/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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.