# Complete Guide to kimi-cli Command-Line Arguments and Options > Master kimi-cli command-line arguments to control session management, UI modes, agent selection, and logging. Explore over 30 options for efficient CLI interaction with this comprehensive guide. - Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli) - Tags: api-reference - Published: 2026-07-27 --- **The `kimi-cli` tool accepts over 30 command-line arguments defined in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) that control session management, UI modes, agent selection, and logging behavior through a Typer-based interface.** The MoonshotAI/kimi-cli repository implements a sophisticated command-line interface built on the **Typer** framework. Understanding the available `kimi-cli` command-line arguments allows you to automate workflows, configure runtime behavior, and integrate the AI agent into shell scripts and CI/CD pipelines. All global options are declared in the CLI callback spanning lines 79 through 200 of the main entry file. ## Core Architecture and Option Parsing The CLI defines a single top-level command (`kimi`) using Typer's callback mechanism in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py). The entry point in [`src/kimi_cli/cli/__main__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__main__.py) installs crash handlers and invokes this Typer application, which then instantiates the `KimiCLI` runtime defined in [`src/kimi_cli/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/app.py) using the parsed options. ## Meta and Debugging Options Control basic CLI behavior and troubleshooting output with these flags: - **`--version` / `-V`** — Display the current CLI version and exit immediately. - **`--verbose`** — Enable verbose output to print extra diagnostic information during execution. - **`--debug`** — Activate debug-level logging and append full stack traces when failures occur. ## Session and Configuration Management Manage workspace context, persist sessions, and override configuration defaults: - **`--work-dir` / `-w `** — Set the working directory for the agent session. The path must exist before invocation. - **`--add-dir `** — Add extra directories to the workspace scope. This flag is repeatable to include multiple paths. - **`--session` / `--resume` / `-S` / `-r `** — Resume a specific session by its identifier. When invoked without an ID, it launches an interactive picker. - **`--continue` / `-C`** — Continue the most recent session associated with the current working directory. - **`--config `** — Provide a TOML or JSON configuration string inline. - **`--config-file `** — Load configuration from a specific file. Defaults to `~/.kimi/config.toml` if not specified. - **`--model` / `-m `** — Select the LLM model to use, overriding any configuration file setting. - **`--thinking` / `--no-thinking`** — Toggle the "thinking" mode, with the default value sourced from the configuration file. ## Execution Modes and UI Controls Configure how the agent interacts with users and handles tool approvals: - **`--yolo` / `--yes` / `-y` / `--auto-approve`** — Automatically approve every tool call without prompting. - **`--plan`** — Start the CLI in plan mode for structured task decomposition. - **`--afk`** — Enable "away-from-keyboard" mode, which auto-dismisses questions and auto-approves tool calls. - **`--prompt` / `-p` / `--command` / `-c `** — Supply a one-off prompt to the agent. Without this flag, the CLI runs interactively. - **`--print`** — Run in non-interactive "print" mode, auto-dismissing questions and auto-approving tools. - **`--acp`** — Run the deprecated ACP server (superseded by the `kimi acp` subcommand). - **`--wire`** — Run the experimental Wire server. - **`--input-format `** — Specify the input format when using `--print` with piped stdin. - **`--output-format `** — Define the output format for `--print` mode. - **`--final-message-only`** — Emit only the final assistant message. Requires the `--print` flag. - **`--quiet`** — Shortcut combining `--print --output-format text --final-message-only` for silent operation. ## Agent Customization and MCP Integration Customize agent behavior and Model Context Protocol (MCP) configurations: - **`--agent `** — Select a built-in agent specification. The [`agentspec.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/agentspec.py) module provides `DEFAULT_AGENT_FILE` and `OKABE_AGENT_FILE` options. - **`--agent-file `** — Load a custom agent specification from a YAML file. Mutually exclusive with `--agent`. - **`--mcp-config-file `** — Load MCP configuration files in JSON format. This flag is repeatable. - **`--mcp-config `** — Provide MCP configuration inline as a JSON string. This flag is repeatable. - **`--skills-dir `** — Add custom skills directories, overriding automatic discovery. This flag is repeatable. ## Loop Control and Safety Limits Prevent runaway execution with step and retry limits: - **`--max-steps-per-turn `** — Limit the number of steps the agent can take per turn. Uses the configuration default if not specified. - **`--max-retries-per-step `** — Limit retry attempts per individual step. Uses the configuration default if not specified. - **`--max-ralph-iterations `** — Set extra iterations allowed after the first turn in Ralph mode. Use `-1` for unlimited iterations. ## Available Sub-commands The CLI exposes several sub-commands for authentication and specialized interfaces: - **`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 used by the runtime. ## Argument Validation and Mutual Exclusivity The CLI validates mutually exclusive argument groups in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py) (lines 354-561) and raises clear errors when conflicting flags are supplied. The following combinations cannot be used together: - **`--print`**, **`--acp`**, and **`--wire`** — Select only one execution mode. - **`--agent`** versus **`--agent-file`** — Choose either a built-in agent or a custom file. - **`--continue`** versus **`--session`** — Either resume a specific session or continue the most recent one. - **`--config`** versus **`--config-file`** — Provide configuration inline or via file path, but not both. ## 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 current directory while auto-approving all tool calls: ```bash kimi --continue --yolo ``` Use a custom agent specification and add an extra directory to the workspace scope: ```bash kimi --agent-file ./my_custom_agent.yaml --add-dir /opt/project/lib ``` ## Summary - The `kimi-cli` interface is implemented using Typer in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py), with options defined in the main callback function. - Arguments cover six categories: meta/debugging, session management, execution modes, agent customization, loop control, and sub-commands. - **Mutually exclusive groups** prevent conflicting flags like `--print` with `--acp`, or `--continue` with `--session`. - Non-interactive automation is supported through `--print`, `--quiet`, and `--yolo` flags for CI/CD integration. - Custom agents can be loaded via `--agent-file`, while MCP configurations support both file-based (`--mcp-config-file`) and inline JSON (`--mcp-config`) inputs. ## Frequently Asked Questions ### What is the difference between `--session` and `--continue`? The `--session` (or `-S`, `-r`) flag resumes a specific session by its identifier, optionally opening an interactive picker if no ID is provided. The `--continue` (or `-C`) flag automatically resumes the most recent session associated with the current working directory without requiring an explicit ID. These flags 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). ### How do I run kimi-cli in non-interactive mode for scripting? Use the `--print` flag to enable non-interactive mode, which auto-approves tools and dismisses questions. Combine it with `--final-message-only` to output just the assistant's response, or use `--quiet` as a shorthand for `--print --output-format text --final-message-only`. For full automation, add `--yolo` to auto-approve every tool call. ### Can I use multiple MCP configuration files simultaneously? Yes. Both `--mcp-config-file` and `--mcp-config` are repeatable flags. You can specify multiple JSON configuration files using repeated `--mcp-config-file` arguments, or provide multiple inline JSON strings using repeated `--mcp-config` arguments. The CLI aggregates these configurations during runtime initialization. ### Where does kimi-cli store its default configuration? By default, `kimi-cli` loads configuration from `~/.kimi/config.toml`. You can override this path using `--config-file`, or provide configuration inline using `--config` with a TOML or JSON string. The configuration handling is implemented in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py), which processes both file-based and string-based configuration sources.