# How to Customize the Kimi CLI Shell UI: Themes and Keyboard Shortcuts

> Customize Kimi CLI shell UI themes and keyboard shortcuts. Modify config.toml for themes and prompt.py slash.py for key bindings to personalize your experience.

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

---

**You can customize the Kimi CLI shell UI by modifying the `theme` setting in `~/.kimi/config.toml` for visual preferences, or by editing `_KEYBOARD_SHORTCUTS` in [`src/kimi_cli/ui/shell/slash.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/slash.py) and adding handlers in [`src/kimi_cli/ui/shell/prompt.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/prompt.py) for key bindings.**

The Kimi CLI provides an interactive shell experience built on the **Rich** library and **prompt_toolkit**, offering deep customization through specific configuration files and source modules. Whether you prefer a light terminal theme or need custom key bindings for your workflow, the MoonshotAI/kimi-cli repository exposes clean extension points for tailoring the interface.

## Customizing Color Themes

The color system centers on [`src/kimi_cli/ui/theme.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/theme.py), which exposes `set_active_theme` and `get_active_theme` as the primary public API. The active theme is stored in a module-level variable `_active_theme` that defaults to **dark** mode.

### Switching Themes at Runtime

Use the built-in slash command to toggle between palettes without restarting:

```text
/theme dark   # switch to dark (default)

/theme light  # switch to light-mode colours

```

According to the source code in [`src/kimi_cli/ui/shell/slash.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/slash.py), the `/theme` command reads the current theme via `get_active_theme`, updates the global `_active_theme` via `set_active_theme`, writes the new value to `config.theme`, and reloads the UI so the new palette applies immediately.

### Persisting Theme Preferences

To make your theme choice permanent, edit your personal configuration file at `~/.kimi/config.toml`:

```toml
theme = "light"   # or "dark"

```

During `Shell.__init__` in [`src/kimi_cli/ui/shell/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/__init__.py), the config loader automatically calls `set_active_theme` with your stored preference, ensuring the UI initializes with your chosen palette on every start.

### Creating Custom Color Palettes

For advanced customization beyond the built-in dark and light modes, fork the repository and modify [`src/kimi_cli/ui/theme.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/theme.py). This file contains dataclasses including `DiffColors`, `ToolbarColors`, and `MCPPromptColors`, each with light and dark variants (`_DIFF_LIGHT`, `_DIFF_DARK`, etc.).

To add a custom palette (e.g., "solarized"):

1. Define new color constants following the existing pattern
2. Expose them through a helper like `get_theme_colors(name: str)`
3. Extend the `/theme` command logic in [`slash.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/slash.py) to accept your new theme name

## Customizing Keyboard Shortcuts

Keyboard shortcuts are declared in the `_KEYBOARD_SHORTCUTS` constant inside [`src/kimi_cli/ui/shell/slash.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/slash.py). Each entry is a two-item tuple containing the human-readable description and the key binding string (e.g., `("Enter – submit", "enter")`).

### Modifying the Shortcut List

Open [`src/kimi_cli/ui/shell/slash.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/slash.py) and locate the `_KEYBOARD_SHORTCUTS` list. Add or modify entries to document your desired shortcuts:

```python
_KEYBOARD_SHORTCUTS = [
    # existing items...

    ("Ctrl-L – clear the screen", "c-l"),
]

```

The `/help` or `/shortcuts` command automatically renders this list via the `section` helper, so your additions appear in the UI immediately without additional registration.

### Implementing Key Bindings

The actual key handling logic resides in [`src/kimi_cli/ui/shell/prompt.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/prompt.py) within the `handle_running_prompt_key` method. This method receives a key string and dispatches to appropriate actions like `shortcut_newline` or `shortcut_editor`.

To implement a new shortcut:

1. Add your key name to `_KEYBOARD_SHORTCUTS` in [`slash.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/slash.py)
2. Add a conditional branch in `handle_running_prompt_key`:

```python
elif key == "c-l":
    console.clear()                    # clear the Rich console

    track("shortcut_clear_screen")     # telemetry event

```

Changes take effect after restarting the shell process, or you can trigger a live reload using the `/reload` slash command.

## Summary

- **Theme customization** happens through `set_active_theme` in [`src/kimi_cli/ui/theme.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/theme.py), persisted in `~/.kimi/config.toml`, and toggled via the `/theme` slash command.
- **Keyboard shortcuts** are defined in `_KEYBOARD_SHORTCUTS` within [`src/kimi_cli/ui/shell/slash.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/slash.py) and implemented in `handle_running_prompt_key` in [`src/kimi_cli/ui/shell/prompt.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/prompt.py).
- The default theme variable `_active_theme` defaults to **dark** mode but respects your config file on initialization.
- Custom color palettes require modifying dataclasses like `DiffColors` and `ToolbarColors` in the theme module.
- New key bindings automatically appear in the help panel because the UI renders the `_KEYBOARD_SHORTCUTS` list directly.

## Frequently Asked Questions

### How do I permanently set the Kimi CLI to use light mode?

Edit `~/.kimi/config.toml` and set `theme = "light"`. The `Shell` class initialization in [`src/kimi_cli/ui/shell/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/__init__.py) automatically calls `set_active_theme` with this value when the process starts, loading the light color palette defined in [`src/kimi_cli/ui/theme.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/theme.py).

### Can I add custom keyboard shortcuts without modifying the source code?

Currently, no. The `_KEYBOARD_SHORTCUTS` list and the `handle_running_prompt_key` dispatcher in [`src/kimi_cli/ui/shell/prompt.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/prompt.py) are static definitions. To add shortcuts, you must edit [`src/kimi_cli/ui/shell/slash.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/slash.py) to register the description and [`src/kimi_cli/ui/shell/prompt.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/prompt.py) to implement the behavior, then restart or use `/reload`.

### Where are the color definitions stored for the dark and light themes?

Color definitions live in [`src/kimi_cli/ui/theme.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/theme.py) as module-level constants like `_DIFF_DARK`, `_DIFF_LIGHT`, `_TOOLBAR_DARK`, and `_TOOLBAR_LIGHT`. These populate dataclasses including `DiffColors` and `ToolbarColors` that the UI queries at runtime through helpers like `get_prompt_style` and `get_toolbar_colors`.

### What file controls the persistence of my theme preference?

The `theme` field is persisted in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py), which manages the `~/.kimi/config.toml` file. When you use the `/theme` slash command, it updates both the runtime `_active_theme` variable and writes the value to this configuration file for future sessions.