How to Run kimi-cli Commands: A Complete Guide to the Kimi CLI Interface

The kimi command launches the Kimi Code agent through a Typer-driven interface that supports interactive shell sessions, non-interactive output, ACP server mode, and experimental Wire server protocols, with execution flow defined in src/kimi_cli/cli/__init__.py and bootstrapped via src/kimi_cli/__main__.py.

kimi-cli is the official Python-based command-line interface for MoonshotAI's Kimi Code agent. Whether you need an interactive coding assistant or scriptable automation, understanding how to run kimi-cli commands correctly unlocks the full potential of this tool.

Installation and Basic Invocation

After installing the package from the MoonshotAI/kimi-cli repository, invoke the CLI using the kimi command. The entry point resides in src/kimi_cli/__main__.py, which installs crash handlers and normalizes proxy settings before delegating to the main CLI logic.

# Launch interactive shell (default mode)

kimi

# Display help to see all available options

kimi --help

Understanding the Command Execution Flow

When you execute a kimi-cli command, the system follows a precise six-step bootstrap process defined across the codebase:

1. Bootstrap – src/kimi_cli/__main__.py initializes crash handlers and proxy configuration, then calls cli().

2. Argument Parsing – The Typer callback kimi() in src/kimi_cli/cli/__init__.py validates flags like --session, --model, and --print, ensuring mutually exclusive options are not combined incorrectly.

3. Session Creation – Based on flags such as --session, --continue (-C), or resume (-r), the system invokes Session.create(), Session.find(), or Session.continue_() from src/kimi_cli/session.py to establish context.

4. Configuration Loading – A Config object loads credentials and settings, resolving the final model and provider selection.

5. Agent & Runtime Setup – KimiCLI.create() in src/kimi_cli/app.py constructs the Runtime, loads the agent specification via load_agent(), restores conversation history through Context.restore(), and initializes the KimiSoul core loop.

6. UI Dispatch – The system routes to the appropriate run_* method based on the selected UI mode, instantiating Shell, Print, ACP, or WireServer classes before transferring control to the agent loop.

Available UI Modes and Command Patterns

The kimi-cli supports four distinct UI modes, each optimized for different workflows. All modes share the same core engine but differ in input/output handling.

Interactive Shell Mode (Default)

Running kimi without arguments launches the interactive TUI defined in src/kimi_cli/ui/shell/__init__.py. This mode provides a chat interface where you type prompts or use slash-commands.

# Start interactive session

kimi

# Resume a specific session

kimi -r 2024abcd1234

# Continue the latest session for current directory

kimi -C

Non-Interactive Print Mode

For scripting and automation, use print mode (--print or pipe input). This uses the Print class from src/kimi_cli/ui/print.py to output plain text or JSON.

# One-shot command with explicit print flag

kimi -p "list all Python files in the current directory"

# Pipe input for stdin processing

echo "write a hello-world script in Rust" | kimi --print

# JSON output format for programmatic parsing

kimi --print --output-format json -p "analyze this code"

ACP Server Mode

The Agent Communication Protocol (ACP) server enables IDE integration. Implemented in src/kimi_cli/acp/server.py, this starts an async server on localhost.

# Start ACP server

kimi --acp

Wire Server Mode (Experimental)

For machine-to-machine communication, the experimental Wire server uses a stdio-based protocol defined in src/kimi_cli/wire/server.py.

# Start Wire server

kimi --wire

Session Management Commands

Session persistence allows you to maintain context across invocations. The Session class in src/kimi_cli/session.py handles creation, continuation, and restoration.

Resume an existing session:

# Resume by specific ID

kimi -r SESSION_ID

# Interactive session picker (no ID provided)

kimi -r

Continue the latest session:

The --continue (-C) flag finds the most recent session for your current working directory using Session.continue_().

kimi -C

Advanced Options and Flags

Customize execution behavior with these key flags:

• --model (-m): Override the default model defined in ~/.kimi/config.toml
• --yolo: Auto-approve all tool calls without prompting (use with caution)
• --quiet: Suppress intermediate output, printing only the final assistant message
• --session: Create or attach to a named session

Practical examples:

# Use specific model override

kimi -m gpt-4o-mini -p "explain quicksort"

# Auto-approve dangerous operations

kimi --yolo -p "delete all *.tmp files"

# Quiet mode for clean output

kimi --quiet -p "summarize this repository"

Summary

• Entry Point: src/kimi_cli/__main__.py bootstraps the application and calls the Typer CLI defined in src/kimi_cli/cli/__init__.py
• Four UI Modes: Interactive shell (default), print mode (--print), ACP server (--acp), and Wire server (--wire)
• Session Control: Use -r to resume specific sessions, -C to continue the latest session, and --session for named sessions via Session.create() and Session.find()
• Configuration: Runtime settings and LLM credentials resolve through the Config class before KimiCLI.create() initializes the agent
• Safety Flags: --yolo auto-approves tool calls, while --quiet minimizes output for scripting

Frequently Asked Questions

How do I run a kimi-cli command without entering interactive mode?

Use the --print flag combined with the -p argument to provide your prompt directly. For example: kimi --print -p "refactor this function". Alternatively, pipe content into stdin: cat file.py | kimi --print.

What is the difference between kimi -r and kimi -C?

The -r (resume) flag restores a specific session by ID or opens an interactive picker if no ID is provided, calling Session.find(). The -C (continue) flag automatically resumes the most recent session for your current working directory using Session.continue_(), aborting if none exists.

Where does kimi-cli store session data and configuration?

Sessions are managed through the Session class in src/kimi_cli/session.py, while configuration defaults and model definitions reside in ~/.kimi/config.toml. The Config object in src/kimi_cli/app.py loads these settings at runtime.

Can I use kimi-cli in CI/CD pipelines or scripts?

Yes, use print mode with --print and --output-format json for machine-readable output. Combine with --quiet to suppress non-essential messages and --yolo only if you fully understand the security implications of auto-approving tool calls.

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