Essential kimi-cli Commands: A Complete Guide to MoonshotAI's CLI

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

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 <PATH>: Set the working directory for the agent (directory must exist)
• --add-dir <PATH>: Add extra directories to the workspace scope (repeatable)
• --session <ID> or --resume or -S or -r <ID>: 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 <STRING>: Provide a TOML or JSON configuration string inline
• --config-file <PATH>: Load a configuration file (defaults to ~/.kimi/config.toml)
• --model or -m <NAME>: 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 <TEXT>: 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:

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:

kimi --continue --yolo

Input/Output Format Control

When using --print mode with piped stdin, specify data formats:

• --input-format <FORMAT>: Specify input format for --print mode
• --output-format <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:

• --agent <default|okabe>: Select a built-in agent specification (DEFAULT_AGENT_FILE or OKABE_AGENT_FILE)
• --agent-file <PATH>: 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 <PATH>: Load MCP configuration files in JSON format (repeatable)
• --mcp-config <JSON>: Provide MCP configuration inline as JSON strings (repeatable)
• --skills-dir <PATH>: Add custom skills directories, overriding automatic discovery (repeatable)

Use a custom specification with additional workspace directories:

kimi --agent-file ./my_custom_agent.yaml --add-dir /opt/project/lib

Execution Limits

Control resource usage and iteration limits:

• --max-steps-per-turn <INT>: Limit steps per turn (defaults to config)
• --max-retries-per-step <INT>: Limit retries per step (defaults to config)
• --max-ralph-iterations <INT>: 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:

kimi --session abc123 --verbose

Resume the most recent session for the current working directory:

kimi --continue --yolo

Summary

• kimi-cli provides a Typer-based interface with extensive global options defined in src/kimi_cli/cli/__init__.py (lines 79-200) and entry point handling in 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 and 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.

How do I use a custom agent configuration in kimi-cli?

Specify a custom agent YAML file using the --agent-file <PATH> flag, which overrides the built-in default and okabe agents provided in 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.

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