docs(zh+en): improve CLI section — interaction, slash-commands, new pages, full EN translation#386
Conversation
…omization, reference zh improvements: - interaction: add image/video paste, expand approval flow, Plan/YOLO/Auto modes - slash-commands: add /btw, /reload, /reload-tui - kimi-command: add kimi login, kimi acp subcommands - environment-variables: restructure with KIMI_CODE_HOME, KIMI_DISABLE_TELEMETRY, KIMI_MODEL_* sections - mcp: fix anchor link text - datasource: rewrite as official plugin page (new) - use-in-ides: ACP IDE integration for Zed/JetBrains (new) - kimi-acp: ACP capability matrix and method coverage (new) en: full zh→en translation of all 22 CLI pages, zh/en aligned Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
|
Superseded by #372 |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: caa96613ad
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
|
||
| ## Installation | ||
|
|
||
| 1. Run `/plugin` inside Kimi Code CLI |
There was a problem hiding this comment.
/plugins command
In this install flow, users are told to run /plugin, but the built-in slash command registry defines only plugins and no singular alias (apps/kimi-code/src/tui/commands/registry.ts). Because unmatched slash inputs are treated as ordinary messages, following these steps will not open the plugin marketplace; this should be /plugins here and in the repeated confirmation step/localized copy.
Useful? React with 👍 / 👎.
| | `/reload` | — | Reload the current session and apply the latest `config.toml` settings (providers, models, etc.) and `tui.toml` UI preferences, without restarting the CLI | No | | ||
| | `/reload-tui` | — | Reload only the `tui.toml` UI preferences (theme, editor, notifications, etc.) without rebuilding the session | Yes | |
There was a problem hiding this comment.
These rows document /reload and /reload-tui, but the slash command registry has no entries for either command and there is no dispatch path for them as top-level slash commands. Users following this reference will enter commands that the CLI cannot execute as reload operations, so the table should either be backed by implemented commands or remove these rows.
Useful? React with 👍 / 👎.
| - [Configuration files](./configuration-files.md) — full field reference for the `providers` and `models` tables | ||
| - [Config overrides](./overrides-and-precedence.md) — credential resolution priority rules for providers | ||
| - [Environment variables](./environment-variables.md) — credential key names per provider type |
There was a problem hiding this comment.
These next-step links use filenames that do not exist under docs/en/configuration (configuration-files.md, overrides-and-precedence.md, and environment-variables.md); the actual pages are config-files.md, overrides.md, and env-vars.md. Clicking any of these from the rendered docs will land on a 404, and the same stale slugs appear in other edited configuration links.
Useful? React with 👍 / 👎.
|
|
||
| ## Next steps | ||
|
|
||
| - [Keyboard Shortcuts](./keyboard-shortcuts.md) — Quick reference for TUI keyboard operations |
There was a problem hiding this comment.
keyboard.md
The reference page in this directory is keyboard.md, not keyboard-shortcuts.md, so this new next-step link resolves to a missing page in the generated docs. Users navigating from the slash-command reference will get a 404; the Chinese mirror has the same bad target.
Useful? React with 👍 / 👎.
| | --- | --- | --- | --- | | ||
| | `default_model` | `string` | — | Default model alias; must be defined in `models` | | ||
| | `default_thinking` | `boolean` | `false` | Whether new sessions enable Thinking (deep reasoning) mode by default; can be toggled from the model menu inside a session. Even when set to `true`, `[thinking].mode = "off"` will still force Thinking off | | ||
| | `default_permission_mode` | `string` | `manual` | Default permission mode for new sessions; one of `manual` (prompt each time), `auto` (auto-approve read operations), or `yolo` (auto-approve everything) | |
There was a problem hiding this comment.
auto permission mode
For users setting default_permission_mode = "auto" from this table, describing auto as only auto-approving read operations is unsafe: the permission policy approves any non-denied tool call before the normal read/write fallback rules, and only denies AskUserQuestion specially. That means write and shell calls can proceed without prompts in auto mode, so this entry should not imply it is read-only-safe.
Useful? React with 👍 / 👎.
| **`CronCreate`** accepts `cron` (a standard 5-field cron expression in the user's local timezone: `minute hour day-of-month month day-of-week`), `prompt` (the text to re-inject when the schedule fires, capped at 8 KB UTF-8), and an optional `recurring` (default `true`; pass `false` for a one-shot reminder that fires once and then auto-deletes). The tool requires the expression to have at least one fire within five years and rejects one-shot tasks whose next fire would land more than ~350 days in the future (typically a pinned day/month that already passed this year). On success it returns an 8-character hex `id`, a human-readable `humanSchedule` (e.g. `every 5 minutes`), the `recurring` flag, and `nextFireAt` (the ISO timestamp of the next post-jitter fire). The approval scope is tied to the exact `(cron, prompt, recurring)` payload — re-approving once does not authorize later schedules. `CronCreate` is also blocked in Plan mode. | ||
| **`CronCreate`** accepts `cron` (a standard 5-field cron expression in the user's local timezone: `minute hour day-of-month month day-of-week`), `prompt` (the text to inject when triggered; UTF-8 limit 8 KB), and optional `recurring` (defaults to `true`; pass `false` for a one-time reminder that auto-deletes after firing). On success, returns an 8-hex-digit `id`, a human-readable `humanSchedule` (e.g., `every 5 minutes`), and `nextFireAt` (the ISO timestamp of the next fire time). | ||
|
|
||
| To prevent all users from firing at the same time on the hour, the scheduler applies deterministic jitter: recurring tasks are shifted forward by `min(10% of the period, 15 minutes)`; one-time tasks that fall exactly on `:00` or `:30` are moved forward by up to 90 seconds. If the scheduler misses several fire times (e.g., because the laptop was sleeping), it fires only once on wake-up — the prompt is wrapped in a `<cron-fire>` envelope with a `coalescedCount`. Recurring tasks that have been alive for more than 7 days fire one final time with `stale="true"` and are then automatically deleted; call `CronCreate` again to keep them. |
There was a problem hiding this comment.
This reverses the behavior of one-time scheduled tasks: oneShotJitteredNextCronRunMs subtracts up to 90 seconds from tasks that land on :00 or :30 (unless the created-at budget would make that impossible), so these reminders can fire earlier than the requested time, not later. Users relying on reminders or checks not to run before a deadline will be misled by the new wording.
Useful? React with 👍 / 👎.
| ``` | ||
|
|
||
| For multi-file refactors, use Plan mode to confirm the plan first. Use `/fork` to explore alternative approaches. | ||
| For multi-file refactors, use Plan mode first to confirm the approach. You can also use `/fork` to create an experimental branch — if you don't like the result, just switch back to the original session. |
There was a problem hiding this comment.
/fork a branch
In this refactor guidance, /fork is described as creating an experimental branch, but the command only forks the Kimi session and keeps the same working directory; it does not create a Git branch or isolate filesystem edits. A user following this advice can make real file changes in the shared checkout while expecting to be able to discard them by switching back to the original session.
Useful? React with 👍 / 👎.
|
|
||
| ### `kimi acp` | ||
|
|
||
| Switch Kimi Code CLI to ACP (Agent Client Protocol) mode, communicating with an IDE via JSON-RPC over stdin/stdout so the editor can directly drive kimi's sessions and tool calls. You typically do not need to run this manually — the IDE starts it as a subprocess entry point. For configuration, see [Using in IDEs](../use-in-ides.md); for technical details, see the [kimi acp reference](./kimi-acp.md). |
There was a problem hiding this comment.
This new subcommand section points to ../use-in-ides.md, which does not exist from docs/en/reference; the IDE guide is under ../guides/ides.md. The same section later links migration to ../cli-migration.md instead of ../guides/migration.md, so readers following these references from the generated docs hit 404s.
Useful? React with 👍 / 👎.
| `KIMI_CODE_HOME` overrides Kimi Code CLI's data root directory, defaulting to `~/.kimi-code`. The CLI's own application data, `kimi-core`'s config, the ripgrep cache, and OAuth credentials all land under this directory. | ||
| ### `KIMI_CODE_HOME` | ||
|
|
||
| Overrides the data root directory; the default is `~/.kimi-code`. Once set, the config file, sessions, logs, OAuth credentials, and all other data land under the new path: |
There was a problem hiding this comment.
When users set KIMI_CODE_HOME for isolation, this sentence promises that all other data moves there, but the implementation and the data-locations page both keep notable data elsewhere: native/tool cache uses KIMI_CODE_CACHE_DIR or the platform cache directory, and user skill discovery still uses home-relative .kimi-code/skills / .agents/skills. This should be scoped to the data root contents or call out those exceptions so users don't accidentally share cache/skills across supposedly isolated homes.
Useful? React with 👍 / 👎.
1 participant
Summary
Comprehensive update to the Kimi Code CLI documentation section, covering both Chinese (zh) content improvements and a full English (en) translation.
zh improvements
/btw(side-channel conversation),/reload(reload session + config),/reload-tui(reload UI prefs only)kimi login(non-interactive OAuth) andkimi acp(ACP IDE mode) subcommandsKIMI_CODE_HOME,KIMI_DISABLE_TELEMETRY,KIMI_MODEL_*kimi acpcapability matrix and ACP method coverage tableen translation
Full zh→en translation of all 22 CLI pages. New English pages added for:
interaction,sessions,use-cases,use-in-ides,customization/datasource,reference/kimi-acp. All existing English pages updated to match current Chinese versions.Test plan
/reload,/reload-tui,/btwappear correctly in slash-commands reference tablekimi loginandkimi acpappear correctly in kimi-command reference🤖 Generated with Claude Code