# How to Report a Bug in Kimi-CLI: A Complete Guide

> Learn how to report a bug in Kimi-CLI effectively. Enable debug mode, capture logs, document your environment, and submit a detailed GitHub issue for quick resolution.

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

---

**Report bugs in Kimi-CLI by enabling debug mode with `--debug`, capturing the full log output, documenting your environment (Python, uv, and OS versions), and submitting a detailed issue via the GitHub bug report template at [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/.github/ISSUE_TEMPLATE/bug_report.md).**

Kimi-CLI is an extensible Python command-line interface that orchestrates large-language-model (LLM) agents through a layered architecture. When something goes wrong, providing maintainers with precise diagnostic information from the source code layers—ranging from the CLI entry point in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) to the wire protocol in [`src/kimi_cli/wire/protocol.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/wire/protocol.py)—is essential for rapid resolution.

## Before You Submit: Search Existing Issues

Before creating a new report, search the [GitHub Issues](https://github.com/MoonshotAI/kimi-cli/issues) tab for similar problems. If you find an existing issue that describes your bug, add your debug logs and environment details as a comment rather than opening a duplicate.

## Capture Debug Logs with the `--debug` Flag

The `--debug` flag activates verbose logging across the runtime layers, including the **Wire protocol** ([`src/kimi_cli/wire/protocol.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/wire/protocol.py)) and **approval subsystem** ([`src/kimi_cli/soul/approval.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/approval.py)). These logs contain timestamps and internal message IDs that map directly to the code execution flow.

Run your command with debug mode enabled:

```bash
uv run kimi --debug <your-command> [options]

```

Capture the complete output to a file for easy uploading:

```bash
uv run kimi --debug <your-command> [options] 2>&1 | tee kimi-debug.log

```

The debug output will include:
- **Wire messages** from [`src/kimi_cli/wire/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/wire/__init__.py)
- **Tool execution** details from [`src/kimi_cli/soul/toolset.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/toolset.py)
- **Agent loop** state transitions from [`src/kimi_cli/soul/kimisoul.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/kimisoul.py)
- **Configuration loading** traces from [`src/kimi_cli/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/app.py)

## Document Your Environment

Include the following details in your report to help maintainers reproduce the environment:

- **Operating System** and version (e.g., Ubuntu 22.04, macOS 14.2)
- **Python version**: `python --version`
- **uv version**: `uv --version`
- **Kimi-CLI version**: `kimi --version` (or `git rev-parse HEAD` if running from source)

## Prepare a Minimal Reproducible Example

Isolate the bug to the smallest possible command or configuration. If the issue involves **custom agents**, include the minimal YAML spec file that triggers the problem. Agent specifications are processed by [`src/kimi_cli/agentspec.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agentspec.py) and loaded during the bootstrap phase in [`src/kimi_cli/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/app.py).

Example minimal agent spec to include in your issue:

```yaml

# minimal-bug-repro.yaml

name: bug-repro
extends: default
tools:
  - import_path: kimi_cli.tools.shell.run_shell
  - import_path: kimi_cli.tools.file.read_file

```

Also include any relevant configuration from `~/.kimi/config.toml` (redact API keys).

## Submit via the GitHub Bug Report Template

The repository includes a structured template at [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/.github/ISSUE_TEMPLATE/bug_report.md). When you click **New issue → Bug report**, the template pre-populates sections for:

- **Title**: A concise description of the failure
- **Description**: What you expected versus what actually happened
- **Reproduction steps**: The exact command line executed
- **Debug logs**: Paste the output captured from `--debug` mode
- **Environment**: Python version, uv version, OS, and Kimi-CLI version
- **Additional context**: Custom agent specs or configuration files

Fill out each section completely. Attach the `kimi-debug.log` file rather than pasting long logs directly into the text box if they exceed 50 lines.

## Summary

- **Search first** to avoid duplicate issues
- **Use `--debug`** to capture detailed logs from the Wire and Soul layers
- **Document your environment** including Python, uv, and OS versions
- **Provide minimal reproduction** steps and custom agent specs if applicable
- **Use the template** at [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/.github/ISSUE_TEMPLATE/bug_report.md) for consistent formatting

## Frequently Asked Questions

### Where does Kimi-CLI store its debug logs?

Kimi-CLI outputs debug information to **stderr** when the `--debug` flag is passed. You must manually redirect this output to a file using shell redirection (e.g., `2>&1 | tee debug.log`). There is no default log file location; the runtime streams logs directly from [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) through the wire protocol layer.

### What information should I redact from debug logs?

Remove sensitive information such as **API keys**, **access tokens**, and **file paths** that may contain personal information. The debug output from [`src/kimi_cli/soul/approval.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/approval.py) may include file contents if the bug involves file operations—review the log carefully before uploading to a public issue.

### Why does the maintainer need my `uv` version?

Kimi-CLI uses `uv` as its package manager and runner. The `uv` version affects how dependencies are resolved and how the virtual environment is constructed, which can impact behavior in [`src/kimi_cli/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/app.py) during the bootstrap phase. Including this information ensures maintainers can recreate your exact execution environment.

### Can I report bugs for custom agent specifications?

Yes, but clearly indicate that the bug involves a **custom agent spec** (YAML file). Include the minimal spec that reproduces the issue, as the bug may reside in the inheritance resolution logic within [`src/kimi_cli/agentspec.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agentspec.py) or the tool injection system in [`src/kimi_cli/soul/toolset.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/toolset.py). If the bug occurs only with specific `extend` values or custom tool imports, include those details in your reproduction steps.