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

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, 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. 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 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.

# 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.

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:

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 within the visualize function (lines 169–177):

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 (CLI args) → src/kimi_cli/ui/print/types.py (enum) → src/kimi_cli/ui/print/visualize.py (rendering logic).
• Set output_format when constructing KimiCLI instances for programmatic use.
• Extend OutputFormat in types.py and add match cases in 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 with your new format, then implement the rendering logic in the match block of 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}