# Complete Guide to kimi-cli Command-Line Options: Flags, Configs, and Run Modes > Explore kimi-cli command-line options. Discover flags, configurations, and run modes to master this powerful AI tool. Enhance your workflow today. - Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli) - Tags: api-reference - Published: 2026-07-19 --- **The kimi-cli tool provides over 30 command-line options across categories including meta flags, basic configuration, run modes, customization, and loop control, all defined in the Typer-based CLI callback 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 implements a powerful AI agent interface built on **Typer**, offering extensive control through global flags and subcommands. Understanding the full suite of **kimi-cli command-line options** enables developers to automate workflows, customize agent behavior, and integrate the tool into CI/CD pipelines. All options are declared and validated in the main CLI callback spanning lines 79-200 of [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py). ## Meta and Diagnostic Flags Control basic CLI behavior and troubleshooting output with these foundational options: - **`--version` / `-V`** — Display the current CLI version and exit immediately. - **`--verbose`** — Enable verbose logging to print extra diagnostic information during execution. - **`--debug`** — Activate debug-level logging and append full stack traces when failures occur. ## Basic Configuration Flags Manage workspaces, sessions, and model selection through these core **kimi-cli command-line options**: - **`--work-dir` / `-w `** — Set the working directory for the agent (the path must exist). - **`--add-dir `** — Add extra directories to the workspace scope (repeatable flag). - **`--session` / `--resume` / `-S` / `-r `** — Resume a specific session by ID, or invoke an interactive picker when no ID is supplied. - **`--continue` / `-C`** — Continue the most recent session associated with the current working directory. - **`--config `** — Provide configuration as a TOML or JSON string inline. - **`--config-file `** — Load configuration from a file (defaults to `~/.kimi/config.toml`). - **`--model` / `-m `** — Select the LLM model to use, overriding any config file setting. - **`--thinking` / `--no-thinking`** — Toggle the "thinking" mode (defaults to config value). ## Run Mode and UI Options Automate interactions and control the user interface behavior: - **`--yolo` / `--yes` / `-y` / `--auto-approve`** — Automatically approve every tool call without prompting. - **`--plan`** — Start the CLI in plan mode for structured task breakdown. - **`--afk`** — Run in "away-from-keyboard" mode, which auto-dismisses questions and auto-approves tools. - **`--prompt` / `-p` / `--command` / `-c `** — Supply a one-off prompt to the agent (otherwise enters interactive mode). - **`--print`** — Enable non-interactive "print" UI that auto-dismisses questions and auto-approves tools. - **`--acp`** — Run the deprecated ACP server (the `kimi acp` subcommand is preferred). - **`--wire`** — Run the experimental Wire server. - **`--input-format `** — Specify input format when using `--print` (requires piped stdin). - **`--output-format `** — Specify output format when using `--print`. - **`--final-message-only`** — Emit only the final assistant message (requires `--print`). - **`--quiet`** — Shortcut combining `--print --output-format text --final-message-only`. ## Customization and Agent Options Extend functionality with custom agents and MCP configurations: - **`--agent `** — Choose 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 default discovery (repeatable). ## Loop Control Parameters Fine-tune execution limits for agent iterations: - **`--max-steps-per-turn `** — Limit the number of steps per turn (default from config). - **`--max-retries-per-step `** — Limit retries per individual step (default from config). - **`--max-ralph-iterations `** — Set extra iterations after the first turn in Ralph mode (`-1` for unlimited). ## Available Subcommands Beyond global flags, `kimi-cli` exposes several dedicated subcommands defined in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py): - **`login`** — Authenticate with a Kimi account. - **`logout`** — Clear stored authentication credentials. - **`term`** — Launch the Toad TUI interface. - **`acp`** — Start the ACP server (preferred over the deprecated `--acp` flag). - **`__background-task-worker`** and **`__web-worker`** — Internal hidden workers utilized by the runtime. ## Validation and Mutual Exclusion The CLI enforces logical constraints across **kimi-cli command-line options** to prevent conflicting configurations. According to the source code 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`** and **`--agent-file`** — Only one agent source may be specified. - **`--continue`** and **`--session`** — Cannot resume a specific session and continue the most recent one concurrently. - **`--config`** and **`--config-file`** — Inline config strings and file-based configs conflict. If conflicting flags are supplied, the CLI raises a clear error before execution begins. ## Practical Usage Examples Run a new session with non-interactive output, printing only the final response: ```bash kimi --print --final-message-only "Explain quantum entanglement in one paragraph." ``` Resume a previous session by ID with verbose logging enabled: ```bash kimi --session abc123 --verbose ``` Continue the most recent session for the working directory while auto-approving all tool calls: ```bash kimi --continue --yolo ``` Execute with a custom agent specification and additional workspace directories: ```bash kimi --agent-file ./my_custom_agent.yaml --add-dir /opt/project/lib --add-dir /opt/project/src ``` ## Summary - **Over 30 global options** are available across meta, configuration, run mode, customization, and loop control categories. - **Source definition** occurs in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) (lines 79-200), with validation logic at lines 354-561. - **Mutual exclusion** prevents conflicting combinations like `--print` with `--acp`, or `--config` with `--config-file`. - **Subcommands** include `login`, `logout`, `term`, and `acp` for specific operational modes. - **Key support files** include [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py) for configuration handling and [`src/kimi_cli/agentspec.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agentspec.py) for built-in agent definitions. ## Frequently Asked Questions ### How do I run kimi-cli without any interactive prompts? Use the **`--print`** flag for non-interactive execution, which auto-dismisses questions and auto-approves tools. For minimal output, combine with **`--final-message-only`** or use the **`--quiet`** shortcut, which automatically applies `--print --output-format text --final-message-only`. ### What is the difference between `--session` and `--continue`? The **`--session`** flag (or `-S`, `-r`, `--resume`) requires a specific session ID to resume, or opens an interactive picker if no ID is provided. The **`--continue`** flag (or `-C`) automatically resumes the most recent session associated with the current working directory without requiring an ID. These options are mutually exclusive 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). ### Can I use both `--config` and `--config-file` simultaneously? No. The CLI treats **`--config`** (inline TOML/JSON string) and **`--config-file`** (path to configuration file) as mutually exclusive options. You must choose one method to supply configuration overrides. If both are provided, the CLI raises a validation error before starting the agent. ### Where are the built-in agent specifications defined? Built-in agents like `default` and `okabe` are defined in [`src/kimi_cli/agentspec.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agentspec.py) as `DEFAULT_AGENT_FILE` and `OKABE_AGENT_FILE` constants. You can reference these with **`--agent`**, or load custom YAML definitions using **`--agent-file`** to override the built-in behavior.