Complete Guide to kimi-cli Command-Line Arguments and Options

The kimi-cli tool accepts over 30 command-line arguments defined in 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. The entry point in 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 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 <PATH> — Set the working directory for the agent session. The path must exist before invocation.
• --add-dir <PATH> — Add extra directories to the workspace scope. This flag is repeatable to include multiple paths.
• --session / --resume / -S / -r <ID> — 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 <STRING> — Provide a TOML or JSON configuration string inline.
• --config-file <PATH> — Load configuration from a specific file. Defaults to ~/.kimi/config.toml if not specified.
• --model / -m <NAME> — 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 <TEXT> — 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 <FORMAT> — Specify the input format when using --print with piped stdin.
• --output-format <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 <default|okabe> — Select a built-in agent specification. The agentspec.py module provides DEFAULT_AGENT_FILE and OKABE_AGENT_FILE options.
• --agent-file <PATH> — Load a custom agent specification from a YAML file. Mutually exclusive with --agent.
• --mcp-config-file <PATH> — Load MCP configuration files in JSON format. This flag is repeatable.
• --mcp-config <JSON> — Provide MCP configuration inline as a JSON string. This flag is repeatable.
• --skills-dir <PATH> — 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 <INT> — Limit the number of steps the agent can take per turn. Uses the configuration default if not specified.
• --max-retries-per-step <INT> — Limit retry attempts per individual step. Uses the configuration default if not specified.
• --max-ralph-iterations <INT> — 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 (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:

kimi --print --final-message-only "Explain quantum entanglement in one paragraph."

Resume a previous session by ID with verbose logging enabled:

kimi --session abc123 --verbose

Continue the most recent session for the current directory while auto-approving all tool calls:

kimi --continue --yolo

Use a custom agent specification and add an extra directory to the workspace scope:

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, 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.

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, which processes both file-based and string-based configuration sources.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}