# Essential kimi-cli Commands: A Complete Guide to MoonshotAI's CLI > Master essential kimi-cli commands with our complete guide. Learn configuration, session management, authentication, and server operations for MoonshotAI's powerful CLI tool. - Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli) - Tags: getting-started - Published: 2026-07-26 --- **The `kimi-cli` tool provides a Typer-based command-line interface with global options for configuration, session management, and run modes, plus sub-commands for authentication and server operations.** MoonshotAI's `kimi-cli` is a powerful command-line interface built on the Typer framework that enables seamless interaction with Kimi AI models. Located in the `MoonshotAI/kimi-cli` repository, the main CLI entry point at [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) defines a comprehensive set of flags and sub-commands categorized into configuration, UI modes, logging, and agent selection, while [`src/kimi_cli/cli/__main__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__main__.py) serves as the entry point that installs crash handlers. This guide covers the essential commands and options available in the callback function spanning lines 79-200, along with validation logic at lines 354-561. ## Global Options and Configuration Flags The `kimi` command accepts numerous global options declared in the CLI callback that control everything from basic configuration to UI behavior. These options are processed before any sub-command execution and are handled by the configuration system in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py). ### Meta and Debugging Options Control CLI behavior and troubleshooting output with these essential flags: - `--version` or `-V`: Display the CLI version and exit immediately - `--verbose`: Print extra diagnostic information during execution - `--debug`: Enable debug-level logging and include stack traces on failure ### Session and Directory Management Manage working context and session persistence using these configuration flags: - `--work-dir` or `-w `: Set the working directory for the agent (directory must exist) - `--add-dir `: Add extra directories to the workspace scope (repeatable) - `--session ` or `--resume` or `-S` or `-r `: Resume a specific session or invoke an interactive picker when no ID is supplied - `--continue` or `-C`: Resume the most recent session for the current working directory **Note:** The CLI validates that `--continue` and `--session` are mutually exclusive, raising an error if both are supplied, as implemented in the validation logic at lines 354-561. ### Model and Behavior Configuration Override default settings and configure the LLM interaction: - `--config `: Provide a TOML or JSON configuration string inline - `--config-file `: Load a configuration file (defaults to `~/.kimi/config.toml`) - `--model` or `-m `: Specify the LLM model to use, overriding config file settings - `--thinking` or `--no-thinking`: Toggle "thinking" mode (defaults to config file value) ## Run Modes and Execution Control The CLI provides multiple execution modes that determine how the agent interacts with tools and user prompts. ### Interactive and Non-Interactive Modes Control the UI behavior and automation level: - `--prompt` or `-p` or `--command` or `-c `: Supply a one-off prompt directly (otherwise prompts interactively) - `--print`: Run in non-interactive "print" mode that auto-dismisses questions and auto-approves tools - `--final-message-only`: Emit only the final assistant message (requires `--print`) - `--quiet`: Shortcut combining `--print --output-format text --final-message-only` *Run a new session printing only the final response:* ```bash kimi --print --final-message-only "Explain quantum entanglement in one paragraph." ``` ### Automation and Safety Flags Configure automatic approval and unattended operation: - `--yolo` or `--yes` or `-y` or `--auto-approve`: Auto-approve every tool call without confirmation - `--afk`: Run in "away-from-keyboard" mode, auto-dismissing questions and auto-approving tools - `--plan`: Start the CLI in plan mode for structured task breakdown *Continue the most recent session with automatic tool approval:* ```bash kimi --continue --yolo ``` ### Input/Output Format Control When using `--print` mode with piped stdin, specify data formats: - `--input-format `: Specify input format for `--print` mode - `--output-format `: Specify output format for `--print` mode ## Agent Customization and Skills Customize the AI agent behavior and extend capabilities through agent specifications and skill directories. ### Agent Selection Options Choose between built-in or custom agent configurations provided by [`src/kimi_cli/agentspec.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agentspec.py): - `--agent `: Select a built-in agent specification (`DEFAULT_AGENT_FILE` or `OKABE_AGENT_FILE`) - `--agent-file `: Load a custom agent YAML file instead of built-in options **Note:** `--agent` and `--agent-file` are mutually exclusive options validated by the CLI logic. ### MCP and Skills Configuration Extend agent capabilities with Model Context Protocol (MCP) configurations: - `--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) *Use a custom specification with additional workspace directories:* ```bash kimi --agent-file ./my_custom_agent.yaml --add-dir /opt/project/lib ``` ### Execution Limits Control resource usage and iteration limits: - `--max-steps-per-turn `: Limit steps per turn (defaults to config) - `--max-retries-per-step `: Limit retries per step (defaults to config) - `--max-ralph-iterations `: Extra iterations after first turn in Ralph mode (`-1` for unlimited) ## Core Sub-commands Beyond global options, `kimi-cli` provides several distinct sub-commands for specific operations. ### Authentication Commands Manage Kimi account credentials: - `kimi login`: Authenticate with a Kimi account and store credentials - `kimi logout`: Clear stored authentication data from the local system ### Interactive Terminal Launch the Toad Terminal User Interface (TUI): - `kimi term`: Start the interactive Toad TUI for enhanced visual interaction ### Server Operations Run specialized server modes (mutually exclusive with `--print`): - `kimi acp`: Start the ACP server (preferred method over the deprecated `--acp` flag) - `kimi --wire`: Run the experimental Wire server (via global flag) - `kimi __background-task-worker`: Internal hidden worker used by the runtime - `kimi __web-worker`: Internal hidden web worker process ## Session Management Examples Practical examples for resuming and managing persistent sessions: *Resume a specific previous session with verbose logging:* ```bash kimi --session abc123 --verbose ``` *Resume the most recent session for the current working directory:* ```bash kimi --continue --yolo ``` ## Summary - **`kimi-cli`** provides a Typer-based interface with extensive global options defined in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) (lines 79-200) and entry point handling in [`src/kimi_cli/cli/__main__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__main__.py) - **Configuration** is controlled via `--config-file`, `--work-dir`, and `--model` flags, with validation ensuring mutually exclusive options are not combined (lines 354-561) - **Session persistence** uses `--session` for specific IDs or `--continue` for the most recent workspace session - **Run modes** range from interactive TUI to non-interactive `--print` and `--quiet` modes for automation - **Sub-commands** include `login`, `logout`, `term`, and `acp` for authentication, TUI access, and server operations - **Customization** is available through `--agent-file`, `--mcp-config`, and `--skills-dir` options processed by [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py) and [`src/kimi_cli/agentspec.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agentspec.py) ## Frequently Asked Questions ### What is the difference between --session and --continue in kimi-cli? The `--session` flag requires a specific session ID to resume that exact conversation state, while `--continue` automatically resumes the most recent session associated with the current working directory. According to the source code at lines 354-561, these flags are mutually exclusive and cannot be used together in the same command. ### How do I run kimi-cli in non-interactive mode for scripts? Use the `--print` flag to enable non-interactive "print" mode, which auto-dismisses questions and auto-approves tools. Combine with `--final-message-only` to output just the assistant's response, or use `--quiet` as a shortcut for `--print --output-format text --final-message-only`. For full automation, add `--yolo` to auto-approve every tool call. ### What are the authentication commands available in kimi-cli? The CLI provides two primary authentication sub-commands: `kimi login` to authenticate with your Kimi account and store credentials locally, and `kimi logout` to clear stored authentication data. These commands manage the authentication state used by the runtime initialized in [`src/kimi_cli/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/app.py). ### How do I use a custom agent configuration in kimi-cli? Specify a custom agent YAML file using the `--agent-file ` flag, which overrides the built-in `default` and `okabe` agents provided in [`src/kimi_cli/agentspec.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agentspec.py). This flag is mutually exclusive with `--agent`, so you must choose either a built-in agent name or a custom file path, not both.