From 426a3650ff14f6e8ca74c8752a4d844fec46be10 Mon Sep 17 00:00:00 2001 From: Tom Santos Date: Wed, 5 Aug 2026 16:46:54 -0300 Subject: [PATCH] docs: align cli option behavior --- docs/en/configuration/env-vars.md | 13 ++++++++++++- docs/en/configuration/overrides.md | 10 ++++++---- docs/en/reference/kimi-command.md | 4 +++- docs/zh/configuration/env-vars.md | 13 ++++++++++++- docs/zh/configuration/overrides.md | 10 ++++++---- docs/zh/reference/kimi-command.md | 4 +++- 6 files changed, 42 insertions(+), 12 deletions(-) diff --git a/docs/en/configuration/env-vars.md b/docs/en/configuration/env-vars.md index 4e519dda47f..d7511d4396f 100644 --- a/docs/en/configuration/env-vars.md +++ b/docs/en/configuration/env-vars.md @@ -1,6 +1,6 @@ # Environment variables -Kimi Code CLI uses environment variables to control a small number of runtime behaviors — relocating the data directory, turning off telemetry, and temporarily switching models without touching the config file. +Kimi Code CLI uses environment variables to control a small number of runtime behaviors — relocating the data directory, turning off telemetry, selecting non-interactive output, and temporarily switching models without touching the config file. ::: warning Important: API keys are not configured here Credential variables such as `KIMI_API_KEY`, `ANTHROPIC_API_KEY`, and `OPENAI_API_KEY` are **not** read automatically from shell environment variables. Running `export KIMI_API_KEY=xxx` in the terminal does not give any provider its key — they must be written in `config.toml` under `[providers.]` or the `[providers..env]` sub-table. @@ -32,6 +32,17 @@ Set to `1` to turn off anonymous telemetry reporting (also accepts `true`, `yes` export KIMI_DISABLE_TELEMETRY=1 ``` +### `KIMI_MODEL_OUTPUT_FORMAT` + +Sets the default output format for non-interactive `-p` / `--prompt` mode. Accepted values are `text` and `stream-json`: + +```sh +export KIMI_MODEL_OUTPUT_FORMAT="stream-json" +kimi -p "List changed files" +``` + +An explicit `--output-format` flag has higher priority. The variable is ignored outside prompt mode, and an invalid value causes startup to fail. Despite its name, it does not require `KIMI_MODEL_NAME`. + ### `KIMI_MODEL_*` family Switch models temporarily without modifying `config.toml` — when `KIMI_MODEL_NAME` is set, the CLI synthesizes a temporary provider in memory; the change does not persist after restart. See [Define a model from environment variables](#define-a-model-from-environment-variables-kimi-model). diff --git a/docs/en/configuration/overrides.md b/docs/en/configuration/overrides.md index c59a1b28d27..fcda766e8fe 100644 --- a/docs/en/configuration/overrides.md +++ b/docs/en/configuration/overrides.md @@ -66,9 +66,11 @@ Options passed at startup have the highest priority and apply only to the curren Mutual exclusion rules (startup fails if violated): - `--output-format` can only be used with `-p` -- `--prompt` cannot be combined with `--yolo` or `--plan` +- `--prompt` cannot be combined with `--yolo`, `--auto`, or `--plan` - `--continue` and `--session` cannot be used together -- In non-prompt mode, `--yolo` and `--plan` cannot be combined with `--continue` or `--session` +- `--yolo` and `--auto` cannot be used together + +When resuming a session, `--auto`, `--yolo`, or `--plan` can temporarily override its saved permission or plan mode. ::: tip `--skills-dir` is a one-shot replacement that only affects the current startup. To persistently add search directories, write `extra_skill_dirs` in `config.toml` (see [Agent Skills](../customization/skills.md)). @@ -89,10 +91,10 @@ KIMI_CODE_HOME="$PWD/.kimi-sandbox" kimi KIMI_API_KEY = "sk-test" ``` -**Skip approval for batch tasks**: +**Run a batch task non-interactively** — prompt mode uses auto permission automatically: ```sh -kimi --yolo -p "Batch rename the following files..." +kimi -p "Batch rename the following files..." ``` **Enter Plan mode temporarily** (to make it permanent, set `default_plan_mode = true` in the config file): diff --git a/docs/en/reference/kimi-command.md b/docs/en/reference/kimi-command.md index 36480081d2e..fbd86644216 100644 --- a/docs/en/reference/kimi-command.md +++ b/docs/en/reference/kimi-command.md @@ -19,7 +19,7 @@ All flags are optional — run `kimi` directly to enter an interactive session: | `--continue` | `-c` | Continue the most recent session in the current working directory, without specifying an ID manually | | `--model ` | `-m` | Specify a model alias for this launch. When omitted, new sessions use `default_model` from the config file | | `--prompt ` | `-p` | Run a single prompt non-interactively and stream the Assistant output to stdout. This mode does not open the TUI | -| `--output-format ` | | Set the non-interactive output format; supports `text` and `stream-json`. Can only be used with `--prompt`; defaults to `text` | +| `--output-format ` | | Set the non-interactive output format; supports `text` and `stream-json`. Can only be used with `--prompt`. Overrides `KIMI_MODEL_OUTPUT_FORMAT`; otherwise defaults to `text` | | `--yolo` | `-y` | Auto-approve regular tool calls, skipping approval requests | | `--auto` | | Start with auto permission mode; tool approvals are handled automatically and the Agent will not ask the user questions | | `--plan` | | Start a new session in Plan mode — the AI will prioritize read-only tools for exploration and planning | @@ -129,6 +129,8 @@ When you need to parse output programmatically, use the `stream-json` format — kimi -p "List changed files" --output-format stream-json ``` +For scripts that always use JSONL output, set [`KIMI_MODEL_OUTPUT_FORMAT`](../configuration/env-vars.md#kimi-model-output-format). An explicit `--output-format` flag still takes priority. + In `stream-json` mode, regular replies produce an Assistant message; when the model calls a tool, an Assistant message with `tool_calls` is emitted first, followed by the corresponding Tool message, then subsequent Assistant messages. Thinking content is not written to JSONL; tool progress and "resuming session" notices are still written to stderr. ## Subcommands diff --git a/docs/zh/configuration/env-vars.md b/docs/zh/configuration/env-vars.md index 8d44b78734e..981bfbac40d 100644 --- a/docs/zh/configuration/env-vars.md +++ b/docs/zh/configuration/env-vars.md @@ -1,6 +1,6 @@ # 环境变量 -Kimi Code CLI 通过环境变量控制少数运行时行为——迁移数据目录、关闭遥测、不改配置文件临时切换模型。 +Kimi Code CLI 通过环境变量控制少数运行时行为——迁移数据目录、关闭遥测、选择非交互输出格式，以及不改配置文件临时切换模型。 ::: warning 重要：API 密钥不在这里配置 `KIMI_API_KEY`、`ANTHROPIC_API_KEY`、`OPENAI_API_KEY` 等密钥变量**不会**从 shell 环境变量自动读取。在终端里 `export KIMI_API_KEY=xxx` 不会让任何供应商获得密钥——必须写在 `config.toml` 的 `[providers.]` 段或 `[providers..env]` 子表里。 @@ -32,6 +32,17 @@ export KIMI_CODE_HOME="/path/to/custom/kimi-code" export KIMI_DISABLE_TELEMETRY=1 ``` +### `KIMI_MODEL_OUTPUT_FORMAT` + +设置非交互 `-p` / `--prompt` 模式的默认输出格式。合法值为 `text` 和 `stream-json`： + +```sh +export KIMI_MODEL_OUTPUT_FORMAT="stream-json" +kimi -p "列出已修改的文件" +``` + +显式传入的 `--output-format` flag 优先级更高。该变量在非 prompt 模式下会被忽略，值不合法时启动会失败。虽然名称以 `KIMI_MODEL_` 开头，但它不要求设置 `KIMI_MODEL_NAME`。 + ### `KIMI_MODEL_*` 系列 不修改 `config.toml` 临时切换模型——设置 `KIMI_MODEL_NAME` 后，CLI 在内存里合成一个临时供应商，重启后失效。详见[用环境变量定义模型](#用环境变量定义模型-kimi-model)。 diff --git a/docs/zh/configuration/overrides.md b/docs/zh/configuration/overrides.md index e3fed310e40..fa34ec7fe63 100644 --- a/docs/zh/configuration/overrides.md +++ b/docs/zh/configuration/overrides.md @@ -66,9 +66,11 @@ Kimi Code CLI 有三个地方可以影响运行参数：配置文件、命令行 互斥规则（违反时启动报错）： - `--output-format` 只能配合 `-p` 使用 -- `--prompt` 不能同时用 `--yolo` 或 `--plan` +- `--prompt` 不能同时用 `--yolo`、`--auto` 或 `--plan` - `--continue` 和 `--session` 不能同时用 -- 非 prompt 模式下，`--yolo` 和 `--plan` 不能配合 `--continue` 或 `--session` +- `--yolo` 和 `--auto` 不能同时使用 + +恢复会话时，可以通过 `--auto`、`--yolo` 或 `--plan` 临时覆盖会话保存的权限或 Plan 模式。 ::: tip `--skills-dir` 是一次性替换，只影响本次启动。如需长期追加搜索目录，在 `config.toml` 里写 `extra_skill_dirs`（详见 [Agent Skills](../customization/skills.md)）。 @@ -89,10 +91,10 @@ KIMI_CODE_HOME="$PWD/.kimi-sandbox" kimi KIMI_API_KEY = "sk-test" ``` -**跳过审批运行批处理任务**： +**以非交互方式运行批处理任务**——prompt 模式会自动使用 auto 权限： ```sh -kimi --yolo -p "批量重命名以下文件..." +kimi -p "批量重命名以下文件..." ``` **临时进入 Plan 模式**（若想永久生效，在配置文件设 `default_plan_mode = true`）： diff --git a/docs/zh/reference/kimi-command.md b/docs/zh/reference/kimi-command.md index 642026c799d..7229d3566b5 100644 --- a/docs/zh/reference/kimi-command.md +++ b/docs/zh/reference/kimi-command.md @@ -19,7 +19,7 @@ kimi [options] | `--continue` | `-c` | 继续当前工作目录下最近一次的会话，无需手动指定 ID | | `--model ` | `-m` | 为本次启动指定模型别名。省略时新会话使用配置文件中的 `default_model` | | `--prompt ` | `-p` | 非交互执行单次 prompt，并把 Assistant 输出流式写到 stdout。该模式不会打开 TUI | -| `--output-format ` | | 设置非交互输出格式，支持 `text` 与 `stream-json`。仅可与 `--prompt` 一起使用，默认 `text` | +| `--output-format ` | | 设置非交互输出格式，支持 `text` 与 `stream-json`。仅可与 `--prompt` 一起使用。显式 flag 优先于 `KIMI_MODEL_OUTPUT_FORMAT`，后者未设置时默认 `text` | | `--yolo` | `-y` | 自动批准普通工具调用，跳过审批请求 | | `--auto` | | 以 auto 权限模式启动；工具审批自动处理，Agent 不会向用户提问 | | `--plan` | | 以 Plan 模式启动新会话，AI 会优先使用只读工具进行探索和规划 | @@ -129,6 +129,8 @@ kimi -m kimi-code/kimi-for-coding -p "Explain the latest diff" kimi -p "List changed files" --output-format stream-json ``` +需要让脚本始终使用 JSONL 输出时，可以设置 [`KIMI_MODEL_OUTPUT_FORMAT`](../configuration/env-vars.md#kimi-model-output-format)。显式传入的 `--output-format` flag 仍然具有更高优先级。 + `stream-json` 模式下，普通回复输出 Assistant 消息；模型调用工具时，先输出带 `tool_calls` 的 Assistant 消息，再输出对应的 Tool 消息，最后继续输出后续 Assistant 消息。thinking 内容不会写入 JSONL；工具进度和恢复会话提示仍写到 stderr。 ## 子命令