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

> Master kimi-cli commands with this comprehensive guide. Learn to launch the Kimi Code agent for interactive shell sessions, get non-interactive output, and explore server modes.

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

---

**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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) and bootstrapped via [`src/kimi_cli/__main__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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](https://github.com/MoonshotAI/kimi-cli) repository, invoke the CLI using the `kimi` command. The entry point resides in [`src/kimi_cli/__main__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/__main__.py), which installs crash handlers and normalizes proxy settings before delegating to the main CLI logic.

```bash

# 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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/shell/__init__.py). This mode provides a chat interface where you type prompts or use slash-commands.

```bash

# 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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/print.py) to output plain text or JSON.

```bash

# 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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/acp/server.py), this starts an async server on localhost.

```bash

# 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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/wire/server.py).

```bash

# 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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/session.py) handles creation, continuation, and restoration.

**Resume an existing session:**

```bash

# 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_()`.

```bash
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:**

```bash

# 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`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/__main__.py) bootstraps the application and calls the Typer CLI defined in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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`](https://github.com/MoonshotAI/kimi-cli/blob/main/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.