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

> Learn how to set up API keys for Kimi-CLI using environment variables or a config file. Discover which method takes precedence and get started quickly.

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

---

**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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py) and [`src/kimi_cli/llm.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`:

```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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/llm.py).
- **Config file** (`~/.kimi/config.toml`) provides persistent storage using Pydantic `SecretStr` models defined in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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.