# How to Debug Code Generated by kimi-cli: Interactive Shell Commands and CLI Flags > Debug kimi-cli generated code effectively. Learn to use the interactive /debug command, --debug flag for verbose logging, and rollback features to find and fix issues fast. - Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli) - Tags: how-to-guide - Published: 2026-07-19 --- **The `kimi-cli` provides built-in debugging utilities including the interactive `/debug` command for inspecting conversation context, the `--debug` CLI flag for verbose logging, and checkpoint rollback to isolate failures.** Debugging AI-generated code requires visibility into the agent's internal reasoning and tool execution. The `kimi-cli` from the MoonshotAI/kimi-cli repository offers comprehensive debugging tools that let you inspect the full conversation history, trace tool calls, and revert to previous states. These capabilities allow you to step through exactly how the LLM generated specific code blocks and identify where the generation went wrong. ## Using the Interactive `/debug` Command Located in [`src/kimi_cli/ui/shell/debug.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/debug.py), the **`/debug`** command launches an interactive Rich-based pager that renders the complete internal state of the current session. When executed within the kimi-cli shell, it pulls the `history` list from the active `KimiSoul` instance (`app.soul.context.history`) and displays a formatted view of the **Context** object defined in [`src/kimi_cli/soul/context.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/context.py). The debug view presents: - Total message count and token usage statistics - Checkpoint metadata and the file path storing the context - Each message with role-specific syntax highlighting, including system tags and tool-generated content like images or audio If no messages have been processed, the command displays a concise panel indicating an empty history. ### Inspecting Tool Calls and Generated Content Within the `/debug` pager, tool interactions are displayed in dedicated panels labeled **Tool Call**. Each panel shows the function name being invoked, the unique call ID, and JSON-formatted arguments. This formatting makes it easy to spot malformed inputs or incorrect parameters that caused the generated code to fail. ```text # Example debug output showing context inspection: ┌───────────────────────────────────────────────────────────────────────┐ │ #1 USER │ │ Hello, generate a Python script that prints "Hello World". │ ├───────────────────────────────────────────────────────────────────────┤ │ #2 ASSISTANT │ │ ```python │ │ print("Hello World") │ │ ``` │ ├───────────────────────────────────────────────────────────────────────┤ │ #3 TOOL CALL │ │ Function: python_exec │ │ Call ID: 42 │ │ Arguments: │ │ { │ │ "code": "print(\"Hello World\")" │ │ } │ └───────────────────────────────────────────────────────────────────────┘ ``` ## Command-Line Debugging Flags For tracing issues at startup or during automation, use the **`--debug`** flag when launching kimi-cli. This flag, parsed in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py), sets the internal logger to `DEBUG` level and prints full Python tracebacks for any uncaught exceptions. To enable persistent debug logging across sessions, set `KIMI_LOG_LEVEL=debug` in your `~/.kimi/config.toml` configuration file. This captures all internal `logger.debug` calls, including context restoration events, checkpointing operations, and tool loading sequences handled by the logging utilities in [`src/kimi_cli/utils/logging.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/logging.py). ```bash # Run the CLI with debug logging enabled kimi run my_agent --debug ``` ## Low-Level Wire Protocol Inspection For debugging the communication between the UI and agent runtime, use the **`/wire`** slash commands. Implemented in [`src/kimi_cli/wire/protocol.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/wire/protocol.py), these commands expose raw JSON-RPC messages exchanged between components: - **`/wire:dump`**: Exports raw JSON-RPC messages exchanged during the session - **`/wire:replay`**: Replays previous wire protocol interactions This is useful when debugging serialization issues or verifying that tool results are being correctly transmitted back to the LLM. ## Checkpoint Rollback for Isolating Failures The **Context** class in [`src/kimi_cli/soul/context.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/context.py) provides checkpoint functionality that lets you save and restore session states. To revert programmatically: ```python from kimi_cli.soul.context import Context # Restore the session to the first checkpoint await ctx.revert_to(0) ``` You can also manage checkpoints interactively using the `/checkpoint create` and `/checkpoint revert ` shell commands. Create a checkpoint before running uncertain code generation, then revert instantly if the output is corrupted. ## Typical Debugging Workflow 1. **Launch with debug mode**: Start the CLI using `kimi run my_agent --debug` to ensure full tracebacks and debug logging are active. 2. **Reproduce the failure**: Trigger the code generation that produces errors or unexpected output. 3. **Inspect context**: Enter `/debug` in the interactive shell to review the conversation history, token counts, and tool call arguments in the Rich pager. 4. **Isolate with checkpoints**: If a specific generation step introduces errors, create checkpoints before experimental prompts and use `/checkpoint revert ` to roll back immediately. ## Summary - The **`/debug`** command in [`src/kimi_cli/ui/shell/debug.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/debug.py) provides an interactive Rich pager for inspecting conversation history, tool calls, and token usage. - Use the **`--debug`** CLI flag to enable traceback printing and set log levels to `DEBUG` via [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py). - Configure **`KIMI_LOG_LEVEL=debug`** in `~/.kimi/config.toml` for persistent verbose logging of context operations. - Inspect low-level JSON-RPC communication using **`/wire:dump`** and **`/wire:replay`** from [`src/kimi_cli/wire/protocol.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/wire/protocol.py). - Rollback to previous states using **`ctx.revert_to(id)`** programmatically or **`/checkpoint revert`** interactively to isolate faulty code generation. ## Frequently Asked Questions ### How do I enable debug mode when starting kimi-cli? Append the `--debug` flag to your command, such as `kimi run my_agent --debug`. This configures the logger to output `DEBUG` level messages and ensures full Python tracebacks are printed for any exceptions. ### What information does the `/debug` command display? The command renders a paginated view of the current **Context**, showing the total message count, token usage, checkpoint data, and a formatted history of all interactions including system messages, user prompts, assistant responses, and tool call details with JSON arguments. ### Can I automatically save checkpoints before risky operations? Yes, use the `/checkpoint create` command before triggering uncertain code generation. If the output is incorrect, immediately run `/checkpoint revert ` to restore the previous state, or call `await ctx.revert_to(checkpoint_id)` programmatically from your Python scripts. ### Where does kimi-cli store its debug logs? By default, debug logs write to standard error. To customize logging, set `KIMI_LOG_LEVEL=debug` in your `~/.kimi/config.toml` file, which is processed by the logging utilities in [`src/kimi_cli/utils/logging.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/utils/logging.py).