### Setup and run custom Kimi Soul

Source: https://github.com/moonshotai/kimi-cli/blob/main/examples/custom-kimi-soul/README.md

Run these commands from the example directory to install dependencies and start the custom agent loop.

```sh
cd examples/custom-kimi-soul
uv sync --reinstall
uv run main.py
```

--------------------------------

### Setup and run custom echo soul with uv

Source: https://github.com/moonshotai/kimi-cli/blob/main/examples/custom-echo-soul/README.md

Run these commands from the examples/custom-echo-soul directory to install dependencies and start the custom Soul. Requires uv and Python.

```sh
cd examples/custom-echo-soul
uv sync --reinstall
uv run main.py
```

--------------------------------

### Setup and run kimi-psql with uv and connection options

Source: https://github.com/moonshotai/kimi-cli/blob/main/examples/kimi-psql/README.md

Install dependencies with uv sync --reinstall, then run main.py either with a --conninfo connection URL or with traditional psql arguments and PGPASSWORD. The first command uses a password in the URL; the second uses the PGPASSWORD environment variable.

```sh
cd examples/kimi-psql
uv sync --reinstall

# Connection URL with password
uv run main.py --conninfo 'postgresql://user:pass@host/db'

# Traditional psql arguments with PGPASSWORD env var
PGPASSWORD=yourpass uv run main.py -h localhost -U postgres -d mydb
```

--------------------------------

### Run Kimi CLI Stream JSON example

Source: https://github.com/moonshotai/kimi-cli/blob/main/examples/kimi-cli-stream-json/README.md

Run the example from the project root. Requires uv and the example directory.

```sh
cd examples/kimi-cli-stream-json
uv run main.py
```

--------------------------------

### Run custom tools example

Source: https://github.com/moonshotai/kimi-cli/blob/main/examples/custom-tools/README.md

Navigate to the example directory, sync dependencies with uv, and run the main script.

```sh
cd examples/custom-tools
uv sync --reinstall
uv run main.py
```

--------------------------------

### Get kimi-cli config.toml (TypeScript example)

Source: https://github.com/moonshotai/kimi-cli/blob/main/web/src/lib/api/docs/ConfigApi.md

Example of calling the getConfigTomlApiConfigTomlGet endpoint to retrieve the kimi-cli config.toml. The example creates a ConfigApi instance and calls the method, logging the result or any error. No authorization is required.

```TypeScript
import {
  Configuration,
  ConfigApi,
} from '';
import type { GetConfigTomlApiConfigTomlGetRequest } from '';

async function example() {
  console.log("🚀 Testing  SDK...");
  const api = new ConfigApi();

  try {
    const data = await api.getConfigTomlApiConfigTomlGet();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

--------------------------------

### prompt: JSON-RPC request example

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/customization/wire-mode.md

Example JSON-RPC request for the 'prompt' method. Sends a user input 'Hello' to start an agent turn.

```json
{"jsonrpc": "2.0", "method": "prompt", "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "params": {"user_input": "Hello"}}
```

--------------------------------

### GET /api/work-dirs/startup

Source: https://github.com/moonshotai/kimi-cli/blob/main/web/src/lib/api/docs/WorkDirsApi.md

Retrieves the startup directory where kimi web was started.

```APIDOC
## [GET] /api/work-dirs/startup

### Description
Get the startup directory. Returns the directory where kimi web was started.

### Method
GET

### Endpoint
/api/work-dirs/startup

### Parameters
This endpoint does not need any parameter.

### Response
#### Success Response (200)
- Returns a string representing the startup directory.

#### Response Example
```json
"string"
```

```

--------------------------------

### Run Kimi Code CLI Wire Messages example

Source: https://github.com/moonshotai/kimi-cli/blob/main/examples/kimi-cli-wire-messages/README.md

Run the example from the project root. First change into the example directory, then sync dependencies with uv (reinstalling to ensure a clean environment), and finally execute the main script with uv run.

```sh
cd examples/kimi-cli-wire-messages
uv sync --reinstall
uv run main.py
```

--------------------------------

### Pattern 1: High-level guide with references (Markdown)

Source: https://github.com/moonshotai/kimi-cli/blob/main/src/kimi_cli/skills/skill-creator/SKILL.md

Shows a SKILL.md structure that provides a quick start and links to separate reference files (FORMS.md, REFERENCE.md, EXAMPLES.md) for advanced features. Kimi loads these files only when needed.

```markdown
# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

```

--------------------------------

### Configured Hooks Output Example

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/customization/hooks.md

Example output showing the count of hooks configured for different event types.

```text
Configured Hooks:

  PostToolUse: 1 hook(s)
  PreToolUse: 1 hook(s)
  Notification: 1 hook(s)
  Stop: 1 hook(s)
```

--------------------------------

### set_plan_mode request example

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/customization/wire-mode.md

JSON-RPC request example for set_plan_mode with enabled set to true.

```json
{"jsonrpc": "2.0", "method": "set_plan_mode", "id": "8da7d810-9dad-11d1-80b4-00c04fd430c8", "params": {"enabled": true}}
```

--------------------------------

### MCP configuration file example

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/customization/mcp.md

Example `~/.kimi/mcp.json` configuration. Supports HTTP servers with `url` and `headers`, and stdio servers with `command`, `args`, and `env`.

```json
{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "your-key"
      }
    },
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest"],
      "env": {
        "SOME_VAR": "value"
      }
    }
  }
}
```

--------------------------------

### Install plugin from local directory

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/customization/plugins.md

Installs a plugin from a local directory path.

```sh
kimi plugin install /path/to/my-plugin
```

--------------------------------

### Set up development environment

Source: https://github.com/moonshotai/kimi-cli/blob/main/packages/kosong/README.md

Commands to set up a development environment: clone the repository, install dependencies with uv, and run the make targets for linting, testing, and formatting.

```bash
git clone https://github.com/MoonshotAI/kosong.git
cd kosong
uv sync --all-extras

make check  # run lint and type checks
make test   # run tests
make format # format code
```

--------------------------------

### Bad example: mechanical conversion to headings

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/AGENTS.md

A bad example of documentation structure that fragments content into headings, which the style guide advises against.

```markdown
## Install and upgrade

### System requirements

- Python 3.12+
- Recommend uv

### Install

...

### Upgrade

...
```

--------------------------------

### kimi web examples

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/reference/kimi-command.md

Examples of using the kimi web command with various options: default startup, specifying a port, disabling auto-open, and binding to all network interfaces.

```sh
# Default startup, automatically opens browser
kimi web

# Specify port
kimi web --port 8080

# Don't automatically open browser
kimi web --no-open

# Bind to all network interfaces (allow LAN access)
kimi web --host 0.0.0.0
```

--------------------------------

### Get session by ID - getSessionApiSessionsSessionIdGet

Source: https://github.com/moonshotai/kimi-cli/blob/main/web/src/lib/api/docs/SessionsApi.md

TypeScript example using SessionsApi.getSessionApiSessionsSessionIdGet to fetch a session by its ID. The sessionId is provided as a UUID string. The example logs the response data or catches and logs any error.

```TypeScript
import {
  Configuration,
  SessionsApi,
} from '';
import type { GetSessionApiSessionsSessionIdGetRequest } from '';

async function example() {
  console.log("🚀 Testing  SDK...");
  const api = new SessionsApi();

  const body = {
    // string
    sessionId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
  } satisfies GetSessionApiSessionsSessionIdGetRequest;

  try {
    const data = await api.getSessionApiSessionsSessionIdGet(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

--------------------------------

### Install Kimi SDK with uv

Source: https://github.com/moonshotai/kimi-cli/blob/main/sdks/kimi-sdk/README.md

Initialize a Python 3.12 project with uv, then add the kimi-sdk dependency.

```bash
uv init --python 3.12  # or higher
```

```bash
uv add kimi-sdk
```

--------------------------------

### Example: Get session upload file

Source: https://github.com/moonshotai/kimi-cli/blob/main/web/src/lib/api/docs/SessionsApi.md

TypeScript example that creates a SessionsApi instance, builds a request body with sessionId and path, and calls getSessionUploadFileApiSessionsSessionIdUploadsPathGet. Logs the response or error. The endpoint requires no authorization and returns any type.

```TypeScript
import {
  Configuration,
  SessionsApi,
} from '';
import type { GetSessionUploadFileApiSessionsSessionIdUploadsPathGetRequest } from '';

async function example() {
  console.log("🚀 Testing  SDK...");
  const api = new SessionsApi();

  const body = {
    // string
    sessionId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
    // string
    path: path_example,
  } satisfies GetSessionUploadFileApiSessionsSessionIdUploadsPathGetRequest;

  try {
    const data = await api.getSessionUploadFileApiSessionsSessionIdUploadsPathGet(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

--------------------------------

### Configuration file example

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/configuration/overrides.md

Example ~/.kimi/config.toml showing default_model and provider/model definitions. Used to illustrate how configuration file values are overridden by environment variables and CLI flags.

```toml
default_model = "kimi-for-coding"

[providers.kimi-for-coding]
type = "kimi"
base_url = "https://api.kimi.com/coding/v1"
api_key = "sk-config"

[models.kimi-for-coding]
provider = "kimi-for-coding"
model = "kimi-for-coding"
max_context_size = 262144
```

--------------------------------

### Get file or list directory from session work_dir - getSessionFileApiSessionsSessionIdFilesPathGet

Source: https://github.com/moonshotai/kimi-cli/blob/main/web/src/lib/api/docs/SessionsApi.md

TypeScript example using SessionsApi.getSessionFileApiSessionsSessionIdFilesPathGet to retrieve a file or list a directory from a session's work directory. The request includes sessionId and path parameters. The example logs the response data or catches and logs any error.

```TypeScript
import {
  Configuration,
  SessionsApi,
} from '';
import type { GetSessionFileApiSessionsSessionIdFilesPathGetRequest } from '';

async function example() {
  console.log("🚀 Testing  SDK...");
  const api = new SessionsApi();

  const body = {
    // string
    sessionId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
    // string
    path: path_example,
  } satisfies GetSessionFileApiSessionsSessionIdFilesPathGetRequest;

  try {
    const data = await api.getSessionFileApiSessionsSessionIdFilesPathGet(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

--------------------------------

### Select built-in agent with --agent flag

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/customization/agents.md

Use this command to start Kimi Code CLI with a specific built-in agent. The example selects the 'okabe' agent.

```sh
kimi --agent okabe
```

--------------------------------

### Example usage of kimi_sdk generate

Source: https://github.com/moonshotai/kimi-cli/blob/main/klips/klip-7-kimi-sdk.md

Shows basic usage of the Kimi SDK: create a Kimi provider with base URL, API key, and model, then call generate with a system prompt, tools, and history. The result is an awaitable GenerateResult.

```python
from kimi_sdk import Kimi, Message, generate

kimi = Kimi(
    base_url="https://api.moonshot.ai/v1",
    api_key="sk-xxx",
    model="kimi-k2-turbo-preview",
)

history = [Message(role="user", content="Who are you?")]
result = await generate(chat_provider=kimi, system_prompt="You are a helper.", tools=[], history=history)
```

--------------------------------

### TypeScript example for ConfigToml

Source: https://github.com/moonshotai/kimi-cli/blob/main/web/src/lib/api/docs/ConfigToml.md

Shows how to create a ConfigToml object, serialize it to JSON, and parse it back. The example uses placeholder null values for content and path.

```typescript
import type { ConfigToml } from ''

// TODO: Update the object below with actual values
const example = {
  "content": null,
  "path": null,
} satisfies ConfigToml

console.log(example)

// Convert the instance to a JSON string
const exampleJSON: string = JSON.stringify(example)
console.log(exampleJSON)

// Parse the JSON string back to an object
const exampleParsed = JSON.parse(exampleJSON) as ConfigToml
console.log(exampleParsed)
```

--------------------------------

### Switch to Web UI with /web command

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/reference/kimi-web.md

Enter /web in the terminal to start the Web UI server and open the current session in the browser. Session history remains synchronized.

```bash
/web
```

--------------------------------

### List installed plugins

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/customization/plugins.md

Lists installed plugins.

```sh
kimi plugin list
```

--------------------------------

### cancel request example

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/customization/wire-mode.md

JSON-RPC request example for cancel with no parameters.

```json
{"jsonrpc": "2.0", "method": "cancel", "id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8"}
```

--------------------------------

### Enable AFK mode at startup or toggle during runtime

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/guides/interaction.md

AFK mode auto-approves all tool calls and auto-dismisses AskUserQuestion prompts, allowing unattended operation. Enable it at startup with `kimi --afk` or toggle it during runtime with `/afk`. An orange AFK badge appears in the status bar. `--print` implicitly enables `--afk`. AFK skips all approvals and removes clarifying questions, so only use it when you trust the current scope.

```sh
# Enable at startup
kimi --afk

# Or toggle during runtime
/afk
```

--------------------------------

### Complete TOML configuration example

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/configuration/config-files.md

Complete TOML configuration example showing all top-level items and tables: providers, models, loop_control, background, services, and mcp. Use as a template for a full configuration file.

```toml
default_model = "kimi-for-coding"
default_thinking = false
default_yolo = false
skip_afk_prompt_injection = false
default_plan_mode = false
default_editor = ""
theme = "dark"
show_thinking_stream = true
merge_all_available_skills = true
telemetry = true

[providers.kimi-for-coding]
type = "kimi"
base_url = "https://api.kimi.com/coding/v1"
api_key = "sk-xxx"

[models.kimi-for-coding]
provider = "kimi-for-coding"
model = "kimi-for-coding"
max_context_size = 262144

[loop_control]
max_steps_per_turn = 1000
max_retries_per_step = 3
max_ralph_iterations = 0
reserved_context_size = 50000
compaction_trigger_ratio = 0.85

[background]
max_running_tasks = 4
keep_alive_on_exit = false
agent_task_timeout_s = 900

[services.moonshot_search]
base_url = "https://api.kimi.com/coding/v1/search"
api_key = "sk-xxx"

[services.moonshot_fetch]
base_url = "https://api.kimi.com/coding/v1/fetch"
api_key = "sk-xxx"

[mcp.client]
tool_call_timeout_ms = 60000
```

--------------------------------

### GET /api/sessions/{session_id}/git-diff

Source: https://github.com/moonshotai/kimi-cli/blob/main/web/src/lib/api/docs/SessionsApi.md

Gets git diff statistics for a session.

```APIDOC
## GET /api/sessions/{session_id}/git-diff

### Description
Gets git diff stats.

### Method
GET

### Endpoint
/api/sessions/{session_id}/git-diff

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session.

### Request Example
{}

### Response
#### Success Response (200)
- No response fields are documented.

#### Response Example
{}
```

--------------------------------

### URL action parameters examples

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/reference/kimi-web.md

Example URLs for triggering actions in the Web UI. Use ?action=create to open the create-session dialog, or ?action=create-in-dir&workDir=<path> to create a session in a specified working directory.

```text
http://127.0.0.1:5494?action=create
http://127.0.0.1:5494?action=create-in-dir&workDir=/path/to/project
```

--------------------------------

### replay: JSON-RPC request example

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/customization/wire-mode.md

Example JSON-RPC request for the 'replay' method, with no parameters.

```json
{"jsonrpc": "2.0", "method": "replay", "id": "6ba7b812-9dad-11d1-80b4-00c04fd430c8"}
```

--------------------------------

### Install Kosong with uv

Source: https://github.com/moonshotai/kimi-cli/blob/main/packages/kosong/README.md

Commands to initialize a Python 3.12+ project with uv, add Kosong as a dependency, and optionally install the contrib extra for additional chat providers like Anthropic and Google Gemini.

```bash
uv init --python 3.12  # or higher
```

```bash
uv add kosong
```

```bash
uv add 'kosong[contrib]'
```

--------------------------------

### QuestionRequest JSON-RPC example

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/customization/wire-mode.md

Example JSON-RPC request for a QuestionRequest. The client must respond with a QuestionResponse.

```json
{"jsonrpc": "2.0", "method": "request", "id": "b1a2c3d4-e5f6-7890-abcd-ef1234567890", "params": {"type": "QuestionRequest", "payload": {"id": "q-1", "tool_call_id": "tc-1", "questions": [{"question": "Which language should I use?", "header": "Lang", "options": [{"label": "Python", "description": "Widely used, large ecosystem"}, {"label": "Rust", "description": "High performance, memory safe"}], "multi_select": false}]}}}
```

--------------------------------

### VitePress build and preview commands

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/AGENTS.md

Common commands to install dependencies, run the dev server, build, and preview the docs site, run inside the docs/ directory.

```bash
npm install
```

```bash
npm run dev
```

```bash
npm run build
```

```bash
npm run preview
```

--------------------------------

### event notification example

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/customization/wire-mode.md

JSON-RPC notification example for event with type ContentPart and text payload.

```json
{"jsonrpc": "2.0", "method": "event", "params": {"type": "ContentPart", "payload": {"type": "text", "text": "Hello"}}}
```

--------------------------------

### Clone and prepare Kimi CLI development environment

Source: https://github.com/moonshotai/kimi-cli/blob/main/README.md

Clones the Kimi CLI repository and prepares the development environment. Run `make prepare` after cloning to set up dependencies.

```sh
git clone https://github.com/MoonshotAI/kimi-cli.git
cd kimi-cli

make prepare  # prepare the development environment
```

--------------------------------

### GET /api/sessions/{session_id}/uploads/{path}

Source: https://github.com/moonshotai/kimi-cli/blob/main/web/src/lib/api/docs/SessionsApi.md

Gets an uploaded file from the session's uploads.

```APIDOC
## GET /api/sessions/{session_id}/uploads/{path}

### Description
Gets an uploaded file from the session's uploads.

### Method
GET

### Endpoint
/api/sessions/{session_id}/uploads/{path}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session.
- **path** (string) - Required - The path to the uploaded file.

### Request Example
{}

### Response
#### Success Response (200)
- No response fields are documented.

#### Response Example
{}
```

--------------------------------

### TypeScript example: Create and serialize a GlobalConfig instance

Source: https://github.com/moonshotai/kimi-cli/blob/main/web/src/lib/api/docs/GlobalConfig.md

Shows how to define a GlobalConfig object, log it, convert it to a JSON string, and parse it back. The example uses placeholder null values for all properties and includes a TODO to update with actual values.

```typescript
import type { GlobalConfig } from ''

// TODO: Update the object below with actual values
const example = {
  "defaultModel": null,
  "defaultThinking": null,
  "models": null,
} satisfies GlobalConfig

console.log(example)

// Convert the instance to a JSON string
const exampleJSON: string = JSON.stringify(example)
console.log(exampleJSON)

// Parse the JSON string back to an object
const exampleParsed = JSON.parse(exampleJSON) as GlobalConfig
console.log(exampleParsed)
```

--------------------------------

### Example JSONL output for simple response

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/customization/print-mode.md

Example output for a simple assistant response in JSONL format.

```jsonl
{"role":"assistant","content":"Hello! How can I help you?"}
```

--------------------------------

### StepBegin interface

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/customization/wire-mode.md

Event sent when a step starts. The n field is the step number starting from 1.

```typescript
interface StepBegin {
  /** Step number, starting from 1 */
  n: number
}
```

--------------------------------

### steer: JSON-RPC success response example

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/customization/wire-mode.md

Example success response for the 'steer' method, returning a status of 'steered'.

```json
{"jsonrpc": "2.0", "id": "7ca7c810-9dad-11d1-80b4-00c04fd430c8", "result": {"status": "steered"}}
```

--------------------------------

### Debug MCP server startup with kimi mcp list and kimi mcp test

Source: https://github.com/moonshotai/kimi-cli/blob/main/docs/en/faq.md

Run these commands to debug MCP server startup failures. First, list configured servers with `kimi mcp list`, then test a specific server with `kimi mcp test <server-name>`.

```sh
# View configured servers
kimi mcp list

# Test if server is working
kimi mcp test <server-name>
```