Complete kimi-cli Command Reference: Options, Subcommands, and Usage Examples

The kimi-cli command-line interface provides a single top-level kimi command with over 30 global options and dedicated subcommands for authentication, session management, and agent configuration, all implemented using Typer in src/kimi_cli/cli/__init__.py.

The MoonshotAI/kimi-cli repository delivers a sophisticated terminal interface for interacting with Kimi AI models. Built on the Typer framework, the tool exposes a unified entry point that supports everything from interactive chat sessions to fully automated pipeline execution through carefully organized flags and subcommands defined in the source code.

Global Options and Flag Categories

The main CLI callback in src/kimi_cli/cli/__init__.py (lines 79–200) declares the complete set of global options available to every invocation. These flags control configuration, runtime behavior, and output formatting.

Meta and Debugging Controls

These options provide version information and diagnostic capabilities:

• --version / -V — Display the CLI version and exit immediately.
• --verbose — Enable extra diagnostic information during execution.
• --debug — Activate debug-level logging and append stack traces when failures occur.

Configuration and Session Management

Manage working directories, persistence, and model selection:

• --work-dir / -w <PATH> — Specify the working directory for the agent (must exist).
• --add-dir <PATH> — Add extra directories to the workspace scope (repeatable).
• --session / --resume / -S / -r <ID> — Resume a specific session by ID, or launch an interactive picker when no ID is provided.
• --continue / -C — Resume the most recent session for the current working directory.
• --config <STRING> — Supply a TOML or JSON configuration string inline.
• --config-file <PATH> — Load a configuration file (defaults to ~/.kimi/config.toml).
• --model / -m <NAME> — Override the default LLM model selection.
• --thinking / --no-thinking — Toggle "thinking" mode (default pulled from configuration).

Execution Modes and UI Controls

Control how the agent interacts with the user and executes tool calls:

• --yolo / --yes / -y / --auto-approve — Automatically approve every tool call without prompting.
• --plan — Start the CLI in plan mode for structured task breakdown.
• --afk — Enable "away-from-keyboard" mode, which auto-dismisses questions and auto-approves tools.
• --prompt / -p / --command / -c <TEXT> — Provide a one-off prompt instead of entering interactive mode.
• --print — Run in non-interactive "print" UI mode (auto-dismisses questions and approves tools).
• --acp — Run the deprecated ACP server (superseded by the kimi acp subcommand).
• --wire — Launch the experimental Wire server.
• --input-format <FORMAT> — Specify input format when using --print with piped stdin.
• --output-format <FORMAT> — Define output format for --print mode.
• --final-message-only — Emit only the final assistant message (requires --print).
• --quiet — Shortcut combining --print --output-format text --final-message-only.

Agent Customization and Skills

Configure specialized agent behaviors and external capabilities:

• --agent <default|okabe> — Select a built-in agent specification.
• --agent-file <PATH> — Load a custom agent definition from a YAML file.
• --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).

Loop Control Parameters

Fine-tune iteration limits during agent execution:

• --max-steps-per-turn <INT> — Limit steps per turn (defaults to configuration value).
• --max-retries-per-step <INT> — Limit retry attempts per step.
• --max-ralph-iterations <INT> — Set extra iterations after the first turn in Ralph mode (-1 for unlimited).

Subcommands

Beyond the main callback, src/kimi_cli/cli/__init__.py registers several dedicated subcommands for specific workflows.

Authentication Commands

• kimi login — Authenticate with a Kimi account and store credentials.
• kimi logout — Clear stored authentication tokens and session data.

Utility and Interface Commands

• kimi term — Launch the Toad TUI (Terminal User Interface) for enhanced visual interaction.
• kimi acp — Start the ACP server as a dedicated subcommand (preferred over the deprecated --acp flag).

Internal Runtime Commands

These hidden commands support the runtime infrastructure:

• kimi __background-task-worker — Internal worker for background task processing.
• kimi __web-worker — Internal worker used by the web-facing runtime components.

Command Validation and Mutual Exclusivity

The CLI enforces strict validation to prevent conflicting options. According to the validation logic in src/kimi_cli/cli/__init__.py (lines 354–561), the following groups are mutually exclusive:

• --print, --acp, and --wire — Cannot be used simultaneously.
• --agent vs --agent-file — Choose either a built-in agent or a custom file, not both.
• --continue vs --session — Resume the most recent session or a specific one, exclusively.
• --config vs --config-file — Provide configuration inline or via file path, not both.

When conflicting flags are supplied, the CLI raises a clear error before executing any logic.

Practical Usage Examples

Execute a non-interactive query returning only the final response:

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

Resume a specific previous session 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

Launch with a custom agent specification and add an extra directory to the workspace:

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

Summary

• The kimi-cli uses a single Typer-based entry point defined in src/kimi_cli/cli/__init__.py that accepts extensive global options controlling execution, UI, and agent behavior.
• Meta flags (--version, --verbose, --debug) handle diagnostics, while configuration flags (--session, --continue, --config-file) manage persistence and setup.
• Run mode options (--print, --quiet, --yolo, --afk) enable both interactive and automated/CI-friendly executions.
• The CLI provides dedicated subcommands for authentication (login, logout), interface launching (term), and server management (acp).
• Built-in validation logic prevents mutually exclusive flag combinations, ensuring consistent runtime state.

Frequently Asked Questions

What is the difference between --session and --continue in kimi-cli?

The --session (or -S / -r) flag resumes a specific session by ID, or opens an interactive picker when no ID is provided, while --continue (or -C) automatically resumes the most recent session associated with the current working directory without requiring an ID. These flags are mutually exclusive according to the validation rules in src/kimi_cli/cli/__init__.py.

How do I run kimi-cli in non-interactive mode for CI/CD pipelines?

Use the --print flag combined with --final-message-only and --output-format text, or simply use --quiet which bundles these options. For fully automated execution without user prompts, add --yolo to auto-approve all tool calls: kimi --quiet --yolo "your prompt here".

Can I use multiple MCP configuration files simultaneously?

Yes, the --mcp-config-file option is repeatable, allowing you to load multiple JSON configuration files in a single command. Similarly, you can provide multiple inline configurations using the repeatable --mcp-config flag for JSON strings.

Where does kimi-cli store its default configuration?

By default, the CLI loads configuration from ~/.kimi/config.toml, though this path can be overridden with --config-file. Runtime configuration parsing is handled in src/kimi_cli/config.py, which supports both TOML and JSON formats.

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