Kimi Code CLI Tutorial: Install, Migrate, and Configure

Moonshot replaced the Kimi command-line tool’s runtime, installer, configuration path, interface, and permission system in May 2026. That makes most setup instructions published before then confidently wrong. This Kimi Code CLI tutorial covers the rewritten product: the current install commands, first login, legacy migration, safer permission settings, and a working MCP configuration.

The distinction matters because both generations still use the kimi command. The old Python package was called kimi-cli; the current Kimi Code CLI is a new TypeScript codebase distributed as a native binary or npm package. Same command, different plumbing. A developer can follow a perfectly clear old tutorial and configure the wrong product—a particularly efficient way to waste an afternoon.

Before you install: legacy kimi-cli versus Kimi Code CLI

Moonshot’s Kimi Code release notes document a major version upgrade that rebuilt the CLI from Python and uv on a Node.js foundation. Version 0.31.0 arrived on July 30, 2026, after three months of additions including plugins, scheduled tasks, subagents, a local web interface, and revised automation controls.

Setup detail	Legacy kimi-cli	Current Kimi Code CLI
Runtime	Python and uv	TypeScript, native binary or npm
Recommended install	uv tool install kimi-cli	Official install script
Data directory	~/.kimi/	~/.kimi-code/
Interface	Basic terminal output	Full TUI with approval panels
Extensions	MCP	MCP, skills, plugins, hooks, and subagents

If another guide tells you to install Python 3.13, run uv tool install kimi-cli, or edit ~/.kimi/config.toml, it is documenting the legacy version. Do not mix those files with the new ~/.kimi-code/ configuration.

Kimi Code CLI tutorial: install and run your first task

Install on macOS, Linux, or Windows

The official Kimi Code CLI quick start recommends the native installer. It downloads the latest release, verifies its checksum, and adds the executable to your path. You do not need Node.js for this route.

# macOS or Linux
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

# Windows PowerShell
irm https://code.kimi.com/kimi-code/install.ps1 | iex

# Verify after opening a new terminal
kimi --version

Windows also needs Git for Windows because Kimi uses its bundled Git Bash as the shell environment. If Git Bash lives outside the standard location, set KIMI_SHELL_PATH to the absolute path of bash.exe.

Developers who already have Node.js 22.19.0 or newer can use npm or pnpm instead. Choose this route when your package manager already controls global developer tools; otherwise, the native installer has fewer moving parts.

npm install -g @moonshot-ai/kimi-code
# or
pnpm add -g @moonshot-ai/kimi-code

Log in, initialize, and prompt

Start inside a repository, not a random home directory. The working directory defines the project boundary Kimi sees first.

cd /path/to/your-project
kimi

# Inside the TUI
/login
/init

/login offers Kimi Code OAuth or a Moonshot platform API key. On a headless server, the device flow prints a URL you can open elsewhere; kimi login starts the same flow without entering the TUI. Then /init scans the repository and creates an AGENTS.md file for build commands, architecture notes, and local conventions.

Your first task should be bounded and testable. “Improve this repository” is an invitation to expensive improvisation. Try this instead:

Inspect the authentication module and its tests. Explain the current
flow, propose the smallest fix for the failing refresh-token test,
then wait for approval before editing. Run only the relevant tests.

That prompt tests the useful loop: read, explain, plan, edit, and verify. File changes and shell commands require approval in the default manual mode. If you are comparing that behavior with other terminal agents, our AI coding assistant comparison maps the broader trade-offs.

The everyday controls are compact: /help opens the command panel, /new clears the current context, /compact compresses a long session, and /model switches models. Shell mode also changed from the legacy CLI: type ! in an empty input box, then submit a command. Press Ctrl+B while it runs to move it into the background.

Migrate the old Python kimi-cli without losing sessions

Existing users should install the new CLI first, then run kimi. It detects legacy data under ~/.kimi/ and offers to migrate it. You can trigger the same interactive process later:

kimi migrate

The official migration guide lets you import configuration only or configuration plus selected sessions. It transfers config.toml, MCP declarations, input history, and the sessions you choose. Imported sessions receive an [imported] label.

Two credentials do not cross the bridge: OAuth login and MCP service authorizations. Run /login again and reauthorize protected MCP servers. Migration never deletes or edits the old ~/.kimi/ directory, and rerunning it does not duplicate sessions already imported. That is unusually civil behavior for a major rewrite.

Configure models, project context, and permission modes

Long-term agent settings live in ~/.kimi-code/config.toml; interface preferences live beside them in tui.toml. The configuration reference exposes many provider and runtime options, but a cautious default needs only a few lines:

default_permission_mode = "manual"
default_plan_mode = true

That combination starts new sessions in Plan mode and still asks before side effects. Toggle Plan mode with Shift-Tab when a small, familiar task does not need a formal plan.

One trap catches developers moving from other CLIs: exporting OPENAI_API_KEY, ANTHROPIC_API_KEY, or KIMI_API_KEY does not automatically configure those providers. Persistent credentials belong under the provider tables in config.toml. The special KIMI_MODEL_* variables are the documented exception for temporary model overrides.

Mode	What it does	Best use
Manual	Prompts before writes and commands	First use and unfamiliar repositories
Plan	Builds a read-only plan before changes	Large or risky tasks
YOLO	Auto-approves ordinary tool actions but may still ask questions	Trusted, bounded batch work
Auto	Handles every approval and never asks questions	Controlled unattended automation

Start with Manual or Plan. YOLO can write files and execute commands without confirmation; Auto also covers sensitive access and plan exits. Convenience is not a threat model. Use the six-layer coding-agent security checklist before handing any agent unattended access to a valuable repository.

Add MCP tools, plugins, and subagents after the basics work

Kimi reads user-wide MCP servers from ~/.kimi-code/mcp.json and repository-specific servers from .kimi-code/mcp.json. Project entries override user entries with the same name. The official MCP reference supports stdio, HTTP, and legacy SSE connections.

{
  "mcpServers": {
    "docs": {
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Save that example as .kimi-code/mcp.json, start a new session, and run /mcp to inspect connection status. The interactive /mcp-config command can add, edit, delete, or authorize servers without hand-editing JSON. For a practical documentation-server use case, see the Google Developer Knowledge MCP setup; the server concept carries across MCP clients even though the client configuration differs.

Be careful with project-level stdio servers: their declarations can launch local commands when a session starts. Only enable them in repositories you trust. The same caution applies to third-party plugins, which can bundle skills, MCP servers, slash commands, and lifecycle hooks.

Once the base loop is reliable, /plugins opens the extension manager, while built-in coder, explore, and plan subagents can isolate focused work from the main conversation. These features are the real break from the old CLI: Kimi Code is becoming a programmable local agent runtime, not merely a chat box wearing terminal colors.

The setup test that matters

A successful installation is not the kimi --version output. It is one session that reads the right files, proposes a sensible plan, makes an approved edit, runs a targeted test, and explains the diff. Use kimi upgrade to follow the release cadence instead of pinning your workflow—or your bookmarks—to one model number.

The unresolved question is whether Kimi can keep adding autonomous capabilities without making the trusted-repository boundary too permissive for ordinary developers. The rewrite’s real upgrade is not its one-line installer; it is the shift from a model wrapper to an extensible local automation system. The first release-note entry after v0.31.0 that changes permissions, plugins, or hook controls will show whether the safety layer is advancing as quickly as the agent underneath it.