# How to Customize Kimi-CLI's Output Format: A Complete Guide

> Easily customize Kimi-CLI's output format using the --output-format flag or programmatically. Control response rendering with text, JSON, or custom formats.

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

---

**Use the `--output-format` flag together with `--print` mode to control how responses render, or programmatically set the `output_format` parameter in the `KimiCLI` class to switch between text, JSON, and custom formats.**

Kimi-CLI, the official command-line interface for MoonshotAI's Kimi large language models, provides flexible output formatting options for both interactive terminal sessions and automation pipelines. By customizing Kimi-CLI's output format, you can switch between human-readable text for daily chatting and structured JSON for programmatic integration without altering your core prompt logic.

## How Output Formatting Works

Kimi-CLI implements a three-layer architecture spanning argument parsing, type safety, and rendering logic.

### CLI Argument Definitions

In [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py), the Typer-based CLI defines the `--output-format` option (lines 262–267). This argument accepts string values that map directly to the `OutputFormat` enum. When invoked with `--print`, the system initializes the print UI and passes the chosen format downstream.

### The OutputFormat Enum

Valid formats are declared in [`src/kimi_cli/ui/print/types.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/print/types.py). This enumeration includes `"text"` and `"json"` by default, serving as the source of truth for permitted values throughout the application.

### Visualizer Match Logic

The actual rendering implementation resides in [`src/kimi_cli/ui/print/visualize.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/print/visualize.py) within the `visualize` function (lines 169–177). A `match output_format` block selects the appropriate strategy: streaming plain text or serializing JSON payloads.

## Built-in Output Formats

Kimi-CLI ships with render targets optimized for different use cases.

### Text Format (Default)

Omitting `--output-format` defaults to plain text. This streams the assistant's response directly to stdout with minimal formatting, ideal for terminal reading and copy-paste workflows.

### JSON Format

Setting `--output-format json` serializes the complete response object, including metadata like token consumption and finish reason. This integrates cleanly with shell pipelines and tools like `jq`.

### Quiet Mode

The `--quiet` flag is a convenience wrapper that sets `--output-format text` combined with `--final-message-only`. This suppresses system messages and streaming progress, emitting only the final assistant message.

## Command-Line Customization

Customize output directly from the terminal using these patterns.

```bash

# Default plain-text output with full streaming UI

kimi run --print "Explain the Rust ownership model"

# Structured JSON for programmatic parsing

kimi run --print --output-format json "List top 3 Python web frameworks"

# YAML output (requires adding 'yaml' to OutputFormat enum first)

kimi run --print --output-format yaml "Show git status"

# Quiet mode - only final message, no metadata

kimi run --quiet "Summarize the last 10 lines"

```

## Programmatic Customization

Embed Kimi-CLI in Python applications by instantiating the `KimiCLI` class.

```python
from kimi_cli.app import KimiCLI

cli = KimiCLI(
    ui="print",
    output_format="json",  # Options: "text", "json", or custom values

    final_message_only=False,
)

await cli.run("Explain async/await in Python")

```

The `output_format` string must match a valid `OutputFormat` enum member.

## Adding Custom Output Formats

Support specialized workflows like Markdown or YAML by extending the print UI system.

### Extending the Enum

Add your format identifier to [`src/kimi_cli/ui/print/types.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/print/types.py):

```python
from enum import Enum

class OutputFormat(str, Enum):
    TEXT = "text"
    JSON = "json"
    MARKDOWN = "markdown"  # Custom addition

```

### Implementing the Renderer

Add a corresponding case in [`src/kimi_cli/ui/print/visualize.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/print/visualize.py) within the `visualize` function (lines 169–177):

```python
match output_format:
    case OutputFormat.TEXT:
        print(content)
    case OutputFormat.JSON:
        print(json.dumps(response_dict))
    case OutputFormat.MARKDOWN:
        print(f"## Response\n\n{content}")

```

After reinstalling the package, use `--output-format markdown` or `output_format="markdown"` in Python.

## Summary

- Use `--output-format text|json` with `--print` mode, or `--quiet` for text-only final messages.
- The format flows from [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) (CLI args) → [`src/kimi_cli/ui/print/types.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/print/types.py) (enum) → [`src/kimi_cli/ui/print/visualize.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/print/visualize.py) (rendering logic).
- Set `output_format` when constructing `KimiCLI` instances for programmatic use.
- Extend `OutputFormat` in [`types.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/types.py) and add match cases in [`visualize.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/visualize.py) to support custom formats.

## Frequently Asked Questions

### What output formats does Kimi-CLI support natively?

Kimi-CLI natively supports `"text"` for human-readable output and `"json"` for structured data. The system defaults to `"text"` when using `--print` mode without specifying a format.

### How do I suppress all metadata and stream only the final answer?

Use the `--quiet` flag, which internally configures the output as text and enables `final_message_only` mode. This hides system messages, headers, and token statistics.

### Can I add support for YAML or Markdown output?

Yes. Extend the `OutputFormat` enum in [`src/kimi_cli/ui/print/types.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/print/types.py) with your new format, then implement the rendering logic in the `match` block of [`src/kimi_cli/ui/print/visualize.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/print/visualize.py) (lines 169–177).

### Why must I use `--print` with `--output-format`?

The `--print` flag activates the print-based UI system that implements the `OutputFormat` switching logic. Without it, Kimi-CLI uses the interactive TUI, which manages its own rendering pipeline independently of the format enum.