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

Configure the Kimi-Code CLI by creating a kimi.json or 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.

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 — Static JSON configuration
• 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 takes precedence over 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)

Create a kimi.json file with your API and behavior preferences:

{
  "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)

For dynamic configuration, use TypeScript with full IntelliSense:

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:

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

Windows PowerShell:

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

One-shot usage:

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:

1. Default values (lowest priority)
2. kimi.json or kimi.config.ts in project root
3. 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:

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 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):

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

After (config file + selective overrides):

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

Then use environment variables only for secrets:

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

Summary

• Two config formats: kimi.json for static settings, 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

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 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 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 even in pure JavaScript projects without adding TypeScript dependencies.

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