# Complete kimi-cli Command Reference: Options, Subcommands, and Usage Examples > Explore the comprehensive kimi-cli command reference. Discover over 30 global options and subcommands for authentication, session management, and agent configuration with clear usage examples. - Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli) - Tags: api-reference - Published: 2026-07-25 --- **The `kimi-cli` command-line interface provides a single top-level `kimi` command with over 30 global options and dedicated subcommands for authentication, session management, and agent configuration, all implemented using Typer in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py).** The MoonshotAI/kimi-cli repository delivers a sophisticated terminal interface for interacting with Kimi AI models. Built on the Typer framework, the tool exposes a unified entry point that supports everything from interactive chat sessions to fully automated pipeline execution through carefully organized flags and subcommands defined in the source code. ## Global Options and Flag Categories The main CLI callback in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) (lines 79–200) declares the complete set of global options available to every invocation. These flags control configuration, runtime behavior, and output formatting. ### Meta and Debugging Controls These options provide version information and diagnostic capabilities: - **`--version` / `-V`** — Display the CLI version and exit immediately. - **`--verbose`** — Enable extra diagnostic information during execution. - **`--debug`** — Activate debug-level logging and append stack traces when failures occur. ### Configuration and Session Management Manage working directories, persistence, and model selection: - **`--work-dir` / `-w `** — Specify the working directory for the agent (must exist). - **`--add-dir `** — Add extra directories to the workspace scope (repeatable). - **`--session` / `--resume` / `-S` / `-r `** — Resume a specific session by ID, or launch an interactive picker when no ID is provided. - **`--continue` / `-C`** — Resume the most recent session for the current working directory. - **`--config `** — Supply a TOML or JSON configuration string inline. - **`--config-file `** — Load a configuration file (defaults to `~/.kimi/config.toml`). - **`--model` / `-m `** — Override the default LLM model selection. - **`--thinking` / `--no-thinking`** — Toggle "thinking" mode (default pulled from configuration). ### Execution Modes and UI Controls Control how the agent interacts with the user and executes tool calls: - **`--yolo` / `--yes` / `-y` / `--auto-approve`** — Automatically approve every tool call without prompting. - **`--plan`** — Start the CLI in plan mode for structured task breakdown. - **`--afk`** — Enable "away-from-keyboard" mode, which auto-dismisses questions and auto-approves tools. - **`--prompt` / `-p` / `--command` / `-c `** — Provide a one-off prompt instead of entering interactive mode. - **`--print`** — Run in non-interactive "print" UI mode (auto-dismisses questions and approves tools). - **`--acp`** — Run the deprecated ACP server (superseded by the `kimi acp` subcommand). - **`--wire`** — Launch the experimental Wire server. - **`--input-format `** — Specify input format when using `--print` with piped stdin. - **`--output-format `** — Define output format for `--print` mode. - **`--final-message-only`** — Emit only the final assistant message (requires `--print`). - **`--quiet`** — Shortcut combining `--print --output-format text --final-message-only`. ### Agent Customization and Skills Configure specialized agent behaviors and external capabilities: - **`--agent `** — Select a built-in agent specification. - **`--agent-file `** — Load a custom agent definition from a YAML file. - **`--mcp-config-file `** — Load MCP configuration files in JSON format (repeatable). - **`--mcp-config `** — Provide MCP configuration inline as JSON strings (repeatable). - **`--skills-dir `** — Add custom skills directories, overriding automatic discovery (repeatable). ### Loop Control Parameters Fine-tune iteration limits during agent execution: - **`--max-steps-per-turn `** — Limit steps per turn (defaults to configuration value). - **`--max-retries-per-step `** — Limit retry attempts per step. - **`--max-ralph-iterations `** — Set extra iterations after the first turn in Ralph mode (`-1` for unlimited). ## Subcommands Beyond the main callback, [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) registers several dedicated subcommands for specific workflows. ### Authentication Commands - **`kimi login`** — Authenticate with a Kimi account and store credentials. - **`kimi logout`** — Clear stored authentication tokens and session data. ### Utility and Interface Commands - **`kimi term`** — Launch the Toad TUI (Terminal User Interface) for enhanced visual interaction. - **`kimi acp`** — Start the ACP server as a dedicated subcommand (preferred over the deprecated `--acp` flag). ### Internal Runtime Commands These hidden commands support the runtime infrastructure: - **`kimi __background-task-worker`** — Internal worker for background task processing. - **`kimi __web-worker`** — Internal worker used by the web-facing runtime components. ## Command Validation and Mutual Exclusivity The CLI enforces strict validation to prevent conflicting options. According to the validation logic in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) (lines 354–561), the following groups are mutually exclusive: - **`--print`**, **`--acp`**, and **`--wire`** — Cannot be used simultaneously. - **`--agent`** vs **`--agent-file`** — Choose either a built-in agent or a custom file, not both. - **`--continue`** vs **`--session`** — Resume the most recent session or a specific one, exclusively. - **`--config`** vs **`--config-file`** — Provide configuration inline or via file path, not both. When conflicting flags are supplied, the CLI raises a clear error before executing any logic. ## Practical Usage Examples Execute a non-interactive query returning only the final response: ```bash kimi --print --final-message-only "Explain quantum entanglement in one paragraph." ``` Resume a specific previous session with verbose logging enabled: ```bash kimi --session abc123 --verbose ``` Continue the most recent session for the current directory while auto-approving all tool calls: ```bash kimi --continue --yolo ``` Launch with a custom agent specification and add an extra directory to the workspace: ```bash kimi --agent-file ./my_custom_agent.yaml --add-dir /opt/project/lib ``` ## Summary - The `kimi-cli` uses a single Typer-based entry point defined in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) that accepts extensive global options controlling execution, UI, and agent behavior. - **Meta flags** (`--version`, `--verbose`, `--debug`) handle diagnostics, while **configuration flags** (`--session`, `--continue`, `--config-file`) manage persistence and setup. - **Run mode options** (`--print`, `--quiet`, `--yolo`, `--afk`) enable both interactive and automated/CI-friendly executions. - The CLI provides dedicated **subcommands** for authentication (`login`, `logout`), interface launching (`term`), and server management (`acp`). - Built-in **validation logic** prevents mutually exclusive flag combinations, ensuring consistent runtime state. ## Frequently Asked Questions ### What is the difference between --session and --continue in kimi-cli? The `--session` (or `-S` / `-r`) flag resumes a specific session by ID, or opens an interactive picker when no ID is provided, while `--continue` (or `-C`) automatically resumes the most recent session associated with the current working directory without requiring an ID. These flags are mutually exclusive according to the validation rules in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py). ### How do I run kimi-cli in non-interactive mode for CI/CD pipelines? Use the `--print` flag combined with `--final-message-only` and `--output-format text`, or simply use `--quiet` which bundles these options. For fully automated execution without user prompts, add `--yolo` to auto-approve all tool calls: `kimi --quiet --yolo "your prompt here"`. ### Can I use multiple MCP configuration files simultaneously? Yes, the `--mcp-config-file` option is repeatable, allowing you to load multiple JSON configuration files in a single command. Similarly, you can provide multiple inline configurations using the repeatable `--mcp-config` flag for JSON strings. ### Where does kimi-cli store its default configuration? By default, the CLI loads configuration from `~/.kimi/config.toml`, though this path can be overridden with `--config-file`. Runtime configuration parsing is handled in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py), which supports both TOML and JSON formats.