# How to Configure the Kimi-Code CLI Using Config Files and Environment Variables

> Learn to configure the Kimi-Code CLI easily with config files or environment variables. Customize your settings for seamless integration with MoonshotAI.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: how-to-guide
- Published: 2026-08-16

---

**Configure the Kimi-Code CLI by creating a [`kimi.json`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.json) or [`kimi.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.config.ts) file in your project root, or set environment variables like `KIMI_API_KEY` and `KIMI_BASE_URL` to override defaults.**

The `kimi-code` CLI from MoonshotAI provides flexible configuration through both static config files and runtime environment variables. This guide shows you exactly how each mechanism works based on the implementation in [`apps/kimi-code/src/utils/client-configs.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/utils/client-configs.ts).

## Configuration File Locations and Formats

Kimi-Code searches for configuration files in a specific priority order. Understanding this hierarchy ensures your settings apply as expected.

### Supported Config File Names

The CLI recognizes two file formats:

- **[`kimi.json`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.json)** — Static JSON configuration
- **[`kimi.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.config.ts)** — TypeScript configuration with runtime logic

Place either file in your **project root directory** (where you run `kimi` commands).

### Config File Priority

If both files exist, [`kimi.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.config.ts) takes precedence over [`kimi.json`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.json). This allows teams to start with simple JSON and migrate to TypeScript when they need dynamic configuration.

## Config File Structure and Options

### JSON Configuration ([`kimi.json`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.json))

Create a [`kimi.json`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.json) file with your API and behavior preferences:

```json
{
  "apiKey": "your-moonshot-api-key",
  "baseUrl": "https://api.moonshot.cn/v1",
  "model": "kimi-latest",
  "temperature": 0.3,
  "maxTokens": 4096,
  "timeout": 60000,
  "systemPrompt": "You are a helpful coding assistant."
}

```

### TypeScript Configuration ([`kimi.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.config.ts))

For dynamic configuration, use TypeScript with full IntelliSense:

```typescript
import { defineConfig } from '@moonshotai/kimi-code';

export default defineConfig({
  apiKey: process.env.CUSTOM_API_KEY || 'fallback-key',
  baseUrl: process.env.KIMI_BASE_URL || 'https://api.moonshot.cn/v1',
  model: 'kimi-latest',
  temperature: parseFloat(process.env.TEMP || '0.3'),
  maxTokens: 4096,
  timeout: 60000,
  hooks: {
    beforeRequest: (req) => {
      console.log('Making request:', req.url);
      return req;
    }
  }
});

```

The `defineConfig` helper provides type safety and autocompletion for all supported options.

## Environment Variable Overrides

Every config option can be overridden via environment variables. This is essential for CI/CD pipelines and secret management.

### Core Environment Variables

| Variable | Description | Config Equivalent |
|----------|-------------|-------------------|
| `KIMI_API_KEY` | Authentication key for Moonshot API | `apiKey` |
| `KIMI_BASE_URL` | Custom API endpoint | `baseUrl` |
| `KIMI_MODEL` | Model identifier (e.g., `kimi-latest`) | `model` |
| `KIMI_TEMPERATURE` | Sampling temperature (0-2) | `temperature` |
| `KIMI_MAX_TOKENS` | Maximum response tokens | `maxTokens` |
| `KIMI_TIMEOUT` | Request timeout in milliseconds | `timeout` |

### Setting Environment Variables

**Bash/Zsh:**

```bash
export KIMI_API_KEY="sk-your-key-here"
export KIMI_MODEL="kimi-k2"
kimi code "Explain this file"

```

**Windows PowerShell:**

```powershell
$env:KIMI_API_KEY="sk-your-key-here"
$env:KIMI_MODEL="kimi-k2"
kimi code "Explain this file"

```

**One-shot usage:**

```bash
KIMI_API_KEY="sk-your-key" KIMI_TEMPERATURE="0.1" kimi review src/index.ts

```

## Configuration Loading Order and Precedence

The Kimi-Code CLI resolves configuration through a cascading merge, as implemented in [`client-configs.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/client-configs.ts):

1. **Default values** (lowest priority)
2. **[`kimi.json`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.json)** or **[`kimi.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.config.ts)** in project root
3. **[`kimi.json`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.json)** in parent directories (upward search)
4. **Environment variables** (highest priority)

This means an environment variable always wins over a config file setting, which always wins over defaults.

### Debugging Your Configuration

Use the `--verbose` flag to see which configuration sources are loaded:

```bash
kimi --verbose code "test"

```

Look for lines indicating:
- Config file path discovered
- Environment variables detected
- Final merged configuration (with secrets masked)

## Advanced: Per-Directory Configuration

For monorepos with different settings per package, place [`kimi.json`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.json) files at varying depths:

```

repo-root/
├── kimi.json              # Default for entire repo

├── apps/
│   ├── web/
│   │   └── kimi.json      # Overrides for web app

│   └── api/
│       └── kimi.json      # Overrides for API service

```

Run `kimi` from within `apps/web/` to use that directory's config.

## Migration from Environment-Only Setup

If you're currently using only environment variables, migrating to config files improves reproducibility:

**Before (environment-only):**

```bash
export KIMI_MODEL="kimi-latest"
export KIMI_TEMPERATURE="0.7"
export KIMI_MAX_TOKENS="8192"
kimi code "..."

```

**After (config file + selective overrides):**

```json
// kimi.json
{
  "model": "kimi-latest",
  "temperature": 0.7,
  "maxTokens": 8192
}

```

Then use environment variables only for secrets:

```bash
export KIMI_API_KEY="sk-..."
kimi code "..."

```

## Summary

- **Two config formats**: [`kimi.json`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.json) for static settings, [`kimi.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.config.ts) for dynamic logic with `defineConfig`
- **Environment variables** prefixed with `KIMI_` override all file-based settings
- **Priority order**: defaults → config files (upward search) → environment variables
- **Essential variables**: `KIMI_API_KEY`, `KIMI_BASE_URL`, `KIMI_MODEL`, `KIMI_TEMPERATURE`
- **Implementation reference**: Configuration loading is defined in [`apps/kimi-code/src/utils/client-configs.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/utils/client-configs.ts)

## Frequently Asked Questions

### What happens if I specify both a config file and environment variables?

Environment variables always take precedence. The CLI merges all sources with environment variables at the top of the priority stack. If you set `KIMI_MODEL="kimi-k2"` while your [`kimi.json`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.json) specifies `"model": "kimi-latest"`, the environment variable wins.

### Can I use a global config file outside my project?

Kimi-Code currently searches upward from the working directory only. There is no `~/.kimi.json` global config. For cross-project defaults, use shell environment variables in your `.bashrc`, `.zshrc`, or shell profile, or create a wrapper script that exports common settings.

### Does [`kimi.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.config.ts) require TypeScript to be installed in my project?

No. The CLI bundles its own TypeScript transpilation via `esbuild` or `tsx` (as referenced in the loader implementation). You can use [`kimi.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi.config.ts) even in pure JavaScript projects without adding TypeScript dependencies.