# Where to Find Example Usage of kimi-cli: A Complete Guide to the Examples Directory

> Explore kimi-cli example usage in the examples directory. Learn to run agents, use tools, and build custom plugins with this comprehensive guide.

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

---

**`kimi-cli` ships self-contained example projects in the repository's top-level `examples/` folder that demonstrate how to run the agent, invoke built-in tools, and extend functionality with custom plugins.**

The MoonshotAI/kimi-cli repository provides a comprehensive collection of runnable demonstrations for developers seeking **example usage of kimi-cli**. These projects live in the `examples/` directory and illustrate everything from simple plugin creation to low-level wire protocol integration, all executable with `uv run` without additional setup.

## Exploring the examples/ Directory Structure

The `examples/` folder contains six distinct projects, each focused on specific capabilities of the agent framework. Every subdirectory includes a dedicated README with usage instructions and a runnable entry point.

### Plugin and Tool Development Examples

- **sample-plugin**: Demonstrates creating a simple plugin and calling a custom tool from the CLI. Run with:
  ```bash
  uv run examples/sample-plugin/main.py
  ```

  Source: [[`examples/sample-plugin/README.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/examples/sample-plugin/README.md)](https://github.com/MoonshotAI/kimi-cli/blob/main/examples/sample-plugin/README.md)

- **custom-tools**: Shows how to add user-defined tools (such as a custom `ls` command) and load them via a custom agent specification. Run with:
  ```bash
  uv run examples/custom-tools/main.py
  ```

### Integration and Protocol Examples

- **kimi-psql**: An AI-assisted PostgreSQL REPL that combines the standard `psql` client with the `ExecuteSql` tool. Run with:
  ```bash
  uv run examples/kimi-psql/main.py -h localhost -p 5432 -U postgres -d mydb
  ```

  Source: [[`examples/kimi-psql/README.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/examples/kimi-psql/README.md)](https://github.com/MoonshotAI/kimi-cli/blob/main/examples/kimi-psql/README.md)

- **kimi-cli-wire-messages**: Illustrates how to drive the agent programmatically by sending JSON-RPC wire messages, useful for testing or embedding. Run with:
  ```bash
  uv run examples/kimi-cli-wire-messages/main.py
  ```

### Custom Agent Configurations

- **custom-kimi-soul**: Demonstrates building a bespoke `KimiSoul` instance with a custom toolset. Run with:
  ```bash
  uv run examples/custom-kimi-soul/main.py
  ```

- **custom-echo-soul**: A minimal "echo" soul that returns user input directly, useful for learning the agent loop. Run with:
  ```bash
  uv run examples/custom-echo-soul/main.py
  ```

## Core CLI Usage Patterns

Beyond the example projects, the main entry point in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) provides several command-line modes. These commands demonstrate practical **example usage of kimi-cli** for common workflows:

```bash

# Show the help banner

uv run kimi --help

# Start an interactive session (default AI-assisted terminal)

uv run kimi

# Run one-off commands without entering the REPL

uv run kimi /setup          # LLM configuration wizard

uv run kimi /login          # Authenticate with Kimi Code service

uv run kimi acp             # Launch ACP server mode

uv run kimi mcp list        # List configured MCP servers

uv run kimi web             # Start the built-in web UI

```

## Programmatic Implementation Examples

For developers integrating `kimi-cli` into Python applications, the source code reveals several implementation patterns found in the `examples/` directory.

### Launching the Interactive REPL

To programmatically launch the interactive shell equivalent to `uv run kimi`, instantiate the main CLI coroutine:

```python
import asyncio
from kimi_cli.cli import main as kimi_main

if __name__ == "__main__":
    asyncio.run(kimi_main())   # launches the interactive AI shell

```

### Creating Custom Tools

In [`examples/sample-plugin/scripts/greet.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/examples/sample-plugin/scripts/greet.py), the `Greet` tool extends `CallableTool2` to add custom functionality:

```python
from kimi_cli.tools.tool import CallableTool2, ToolOk

class Greet(CallableTool2):
    name = "Greet"
    description = "Return a friendly greeting."
    async def __call__(self, _: None) -> ToolOk:
        return ToolOk(output="👋 Hello from the sample plugin!")

```

This pattern leverages `kimi_cli.soul.agent.load_agent` and `kimi_cli.soul.runtime.Runtime` to register the tool within a custom agent specification.

### Handling Wire Protocol Messages

For low-level integration, the `examples/kimi-cli-wire-messages` project demonstrates driving the agent via JSON-RPC. The implementation uses `JsonRpcRequest` from [`src/kimi_cli/wire/jsonrpc.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/wire/jsonrpc.py):

```python
from kimi_cli.wire.jsonrpc import JsonRpcRequest
from kimi_cli.soul.kimisoul import KimiSoul

async def demo():
    soul = await create_some_soul()
    request = JsonRpcRequest(method="run", id=1, params={"user_input": "Explain the repo structure"})
    await soul.handle_wire(request)   # processes the request and emits UI events

```

This approach builds a `KimiSoul` instance and feeds it wire messages directly, bypassing the terminal UI.

## Key Source Files for Reference

Understanding these core files provides context for the example implementations:

- **[`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py)**: Typer-based command-line entry point defining the `kimi` command.
- **[`src/kimi_cli/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/app.py)**: Contains `KimiCLI.create` which builds configuration, LLM, and runtime objects.
- **[`src/kimi_cli/soul/kimisoul.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/kimisoul.py)**: Implements the main agent loop that receives input, runs tools, and emits wire events.
- **[`src/kimi_cli/soul/agent.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/agent.py)**: Defines `Runtime` and `Agent` classes that glue together configuration, tools, and the soul.
- **`src/kimi_cli/tools/agent/`**: Directory containing built-in tools (Shell, File, Web) available to the agent.
- **`src/kimi_cli/wire/`**: JSON-RPC wire protocol implementation for UI-to-soul communication.

## Summary

- The **`examples/`** directory contains six self-contained, runnable projects demonstrating **example usage of kimi-cli** ranging from simple plugins to complex protocol integrations.
- All examples execute with `uv run` without additional dependencies, utilizing minimal [`pyproject.toml`](https://github.com/MoonshotAI/kimi-cli/blob/main/pyproject.toml) configurations.
- **Wire-level usage** is demonstrated in `examples/kimi-cli-wire-messages`, showing how to drive `KimiSoul` programmatically via JSON-RPC.
- **Custom tool development** follows the `CallableTool2` pattern shown in `examples/sample-plugin`, integrated through `Runtime` and `Agent` classes.
- Core CLI functionality spans interactive REPLs, one-off commands, ACP server mode, and web UI launch capabilities.

## Frequently Asked Questions

### Where are the kimi-cli examples located in the repository?

All official examples reside in the top-level **`examples/`** folder of the MoonshotAI/kimi-cli repository. Each subdirectory contains a complete, runnable project with its own README and entry point.

### How do I run the kimi-cli examples without installing dependencies?

Each example includes a [`pyproject.toml`](https://github.com/MoonshotAI/kimi-cli/blob/main/pyproject.toml) configured for `uv`. Simply execute `uv run examples/<example-name>/main.py` from the repository root, and `uv` will automatically handle dependencies.

### Which example shows how to create custom tools for kimi-cli?

The **`sample-plugin`** and **`custom-tools`** examples demonstrate extending the agent with user-defined functionality. They show how to subclass `CallableTool2`, implement the `__call__` method, and register tools via the `Runtime` class in [`src/kimi_cli/soul/agent.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/agent.py).

### How can I programmatically control kimi-cli without the terminal UI?

Use the **`kimi-cli-wire-messages`** example, which illustrates driving the agent via JSON-RPC wire messages. This approach creates a `KimiSoul` instance and sends `JsonRpcRequest` objects directly to `handle_wire()`, enabling headless operation or custom UI integration.