Complete Guide to kimi-cli Command-Line Options: Flags, Configs, and Run Modes

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.

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.

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 <PATH> — Set the working directory for the agent (the path must exist).
• --add-dir <PATH> — Add extra directories to the workspace scope (repeatable flag).
• --session / --resume / -S / -r <ID> — 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 <STRING> — Provide configuration as a TOML or JSON string inline.
• --config-file <PATH> — Load configuration from a file (defaults to ~/.kimi/config.toml).
• --model / -m <NAME> — 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 <TEXT> — 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 <FORMAT> — Specify input format when using --print (requires piped stdin).
• --output-format <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 <default|okabe> — Choose 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 default discovery (repeatable).

Loop Control Parameters

Fine-tune execution limits for agent iterations:

• --max-steps-per-turn <INT> — Limit the number of steps per turn (default from config).
• --max-retries-per-step <INT> — Limit retries per individual step (default from config).
• --max-ralph-iterations <INT> — 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:

• 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 (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:

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 working directory while auto-approving all tool calls:

kimi --continue --yolo

Execute with a custom agent specification and additional workspace directories:

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 (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 for configuration handling and 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.

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

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