Skip to content

feat(cli): select an output style via general.outputStyle or --output-style #10283

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
qqqys wants to merge 14 commits into
base: main
Choose a base branch
from
Open

feat(cli): select an output style via general.outputStyle or --output-style #10283

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
0b34f32
feat(cli): select an output style via general.outputStyle or --output…
qqqys Aug 27, 2026
72689c3
fix(cli): survive a non-string output style, and regenerate the setti…
qqqys Aug 27, 2026
2713c78
Merge branch 'main' into feat/output-style-setting
qqqys Aug 28, 2026
31180a0
Merge remote-tracking branch 'upstream/main' into feat/output-style-s…
qqqys Aug 28, 2026
6e4824e
fix(cli): sanitize unknown output style before echoing it (#10283)
qwen-code-dev-bot Aug 28, 2026
4ba2441
Merge branch 'feat/output-style-setting' of https://github.com/qqqys/…
qwen-code-dev-bot Aug 28, 2026
0e6aa86
Merge branch 'main' into feat/output-style-setting
qwen-code-dev-bot Aug 28, 2026
2fa3a5b
Merge branch 'main' into feat/output-style-setting
qwen-code-dev-bot Aug 28, 2026
67edf9e
Merge remote-tracking branch 'origin/main' into feat/output-style-set…
qwen-code-dev-bot Aug 29, 2026
b6e9068
Merge remote-tracking branch 'origin/main' into feat/output-style-set…
qwen-code-dev-bot Aug 29, 2026
34d5874
fix(cli): harden --output-style resolution and settle the deferred re…
qqqys Aug 29, 2026
e730ed1
Merge branch 'main' into feat/output-style-setting
qwen-code-dev-bot Aug 29, 2026
2b84a16
Merge branch 'main' into feat/output-style-setting
qqqys Aug 29, 2026
66393b7
Merge branch 'main' into feat/output-style-setting
qwen-code-dev-bot Aug 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/users/configuration/settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ Settings are organized into categories. Most settings should be placed within th
| Setting | Type | Description | Default |
| ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `general.preferredEditor` | string | The preferred editor to open files in. | `undefined` |
| `general.outputStyle` | string | Name of the output style that shapes how responses are written: `Concise`, `Proactive`, `Explanatory`, or `Learning` (case-insensitive). Leave unset, or set `default`, for the default style. `--output-style` overrides it for one run. | `undefined` |
Comment thread
qqqys marked this conversation as resolved.
Outdated
| `general.vimMode` | boolean | Enable Vim keybindings. | `false` |
| `general.enableAutoUpdate` | boolean | Enable automatic update checks and installations on startup. | `true` |
| `general.showSessionRecap` | boolean | Auto-show a one-line "where you left off" recap when returning to the terminal after being away. Off by default. Use `/recap` to trigger manually regardless of this setting. | `false` |
Expand Down Expand Up @@ -800,6 +801,7 @@ For sandbox image selection, precedence is:
| `--prompt-interactive` | `-i` | Starts an interactive session with the provided prompt as the initial input. | Your prompt text | The prompt is processed within the interactive session, not before it. Cannot be used when piping input from stdin. Example: `qwen -i "explain this code"` |
| `--system-prompt` | | Overrides the built-in main session system prompt for this run. | Your prompt text | Loaded context files such as `QWEN.md` are still appended after this override. Can be combined with `--append-system-prompt`. |
| `--append-system-prompt` | | Appends extra instructions to the main session system prompt for this run. | Your prompt text | Applied after the built-in prompt and loaded context files. Can be combined with `--system-prompt`. See [Headless Mode](../features/headless) for examples. |
| `--output-style` | | Selects the output style that shapes how responses are written for this run. | Style name | `Concise`, `Proactive`, `Explanatory`, `Learning`, or `default` for no style (case-insensitive). Overrides the `general.outputStyle` setting. An unknown name prints a warning and the session starts with the default style. Has no effect when `--system-prompt` or `QWEN_SYSTEM_MD` replaces the built-in prompt. See [Headless Mode](../features/headless) for examples. |

@qwen-code-ci-bot qwen-code-ci-bot Aug 29, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Suggestion] R8-1: [probe] The added doc rows omit that Learning is silently discarded in headless runs

The new --output-style flag row — and the general.outputStyle settings row at line 83 — enumerate the cases where a style does not apply (an unknown name warns and falls back; --system-prompt / QWEN_SYSTEM_MD replacement has no effect) but omit the third: Learning is silently dropped in headless/non-interactive runs, with no warning anywhere. A user who follows the headless docs and runs qwen -p "query" --output-style Learning — or keeps general.outputStyle: "Learning" in settings.json for their CI/scripted runs — gets the default style back, silently: getCoreSystemPrompt downgrades Learning to no style in headless mode (prompts.ts:463-466) and nothing on that path warns. The settings row has no mention and no link at all, and since the runtime path is fully silent the docs are the only discoverability channel.

Witness:

Probe on intact PR: RECORD headless: containsStyle=false consoleErrorCalls=0 consoleWarnCalls=0 consoleLogCalls=0
                    RECORD interactive: containsStyle=true
With a downgrade-site warning patched in: consoleWarnCalls=1
WARNING: The "Learning" output style is skipped in headless runs because it needs a follow-up reply.

Extend both added rows (settings.md:83 and :805, plus the headless.md note) to state that Learning is ignored in non-interactive/headless runs because it needs a follow-up reply; optionally also emit the existing one-shot warning when the downgrade happens so the silent path becomes observable.

The downgrade itself is intentional — packages/core/src/core/prompts.ts:462 comments // Learning requires a reply to its handoff, which a headless run cannot receive. — so a fix must document/warn around it, not remove it. If a warning is added at the downgrade, please pin it with a test asserting one is emitted when getCoreSystemPrompt receives Learning with interactionMode: 'headless' (no such test exists today), and confirm removing the warning turns it red.

中文说明

新增的 --output-style 参数行以及第 83 行的 general.outputStyle 设置行列举了风格不生效的情形（未知名称会告警并回退；--system-prompt / QWEN_SYSTEM_MD 替换内置提示词时无效），但遗漏了第三种：Learning 在 headless/非交互运行中会被静默丢弃，且没有任何警告。按照 headless 文档运行 qwen -p "query" --output-style Learning 的用户——或在 settings.json 里为 CI/脚本保留 general.outputStyle: "Learning" 的用户——会静默得到默认风格：getCoreSystemPrompt 在 headless 模式下把 Learning 降级为无风格（prompts.ts:463-466），且该路径上不产生任何警告。设置行既没有提及也没有链接，而运行时路径完全静默，因此文档是唯一的可发现渠道。

证据（在未修改的 PR 上运行探针）：headless 运行时 containsStyle=false 且 error/warn/log 调用均为 0；interactive 运行时 containsStyle=true；在降级处补上警告后 consoleWarnCalls=1。

建议：扩展两处新增的行（settings.md:83 与 :805，以及 headless.md 的说明块），写明 Learning 在非交互/headless 运行中会被忽略，因为它需要一次后续回复；也可以选择在降级发生处打印现有的一次性警告，让这条静默路径变得可观察。

降级本身是有意为之——prompts.ts:462 的注释写明 "Learning requires a reply to its handoff, which a headless run cannot receive."——因此修复应当围绕它做说明/警告，而不是移除它。如果在降级处新增警告，请补一个测试：当 getCoreSystemPrompt 收到 Learning 且 interactionMode: 'headless' 时断言打印了警告（目前不存在这样的测试），并确认移除该警告后测试变红。

— qwen3.8-max via Qwen Code /review (v0.22.3)

| `--output-format` | `-o` | Specifies the format of the CLI output for non-interactive mode. | `text`, `json`, `stream-json` | `text`: (Default) The standard human-readable output. `json`: A machine-readable JSON output emitted at the end of execution. `stream-json`: Streaming JSON messages emitted as they occur during execution. For structured output and scripting, use the `--output-format json` or `--output-format stream-json` flag. See [Headless Mode](../features/headless) for detailed information. |
| `--input-format` | | Specifies the format consumed from standard input. | `text`, `stream-json` | `text`: (Default) Standard text input from stdin or command-line arguments. `stream-json`: JSON message protocol via stdin for bidirectional communication. Requirement: `--input-format stream-json` requires `--output-format stream-json` to be set. When using `stream-json`, stdin is reserved for protocol messages. See [Headless Mode](../features/headless) for detailed information. |
| `--include-partial-messages` | | Include partial assistant messages when using `stream-json` output format. When enabled, emits stream events (message_start, content_block_delta, etc.) as they occur during streaming. | | Default: `false`. Requirement: Requires `--output-format stream-json` to be set. See [Headless Mode](../features/headless) for detailed information about stream events. |
Expand Down
15 changes: 15 additions & 0 deletions docs/users/features/headless.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,20 @@ qwen -p "Summarize this repository" \
--append-system-prompt "Return exactly three bullets."
```

### Choose an Output Style

Use `--output-style` to pick one of the built-in output styles for this run. A style is a named block of instructions layered onto the built-in prompt that changes how the answer is written — `Concise` leads with the result and drops preamble and narration, `Proactive` starts working instead of proposing, `Explanatory` adds short notes about the codebase along the way. It overrides the `general.outputStyle` setting; `default` selects no style.
Comment thread
qqqys marked this conversation as resolved.

```bash
qwen -p "Why does the build fail on Windows?" --output-style Concise
```

> [!note]
>
> - `Learning` asks you to write part of the code and waits for a reply, so it is skipped in headless runs.
> - An unknown style name prints a warning and the run continues with the default style.
Comment thread
qqqys marked this conversation as resolved.
> - `--output-style` has no effect when `--system-prompt` or `QWEN_SYSTEM_MD` replaces the built-in prompt — a style is only layered onto the built-in prompt.

> [!note]
>
> - `--system-prompt` applies only to the current run's main session.
Expand Down Expand Up @@ -272,6 +286,7 @@ Key command-line options for headless usage:
| `--include-partial-messages` | Include partial messages in stream-json output | `qwen -p "query" --output-format stream-json --include-partial-messages` |
| `--system-prompt` | Override the main session system prompt for this run | `qwen -p "query" --system-prompt "You are a terse reviewer."` |
| `--append-system-prompt` | Append extra instructions to the main session system prompt for this run | `qwen -p "query" --append-system-prompt "Focus on concrete findings."` |
| `--output-style` | Output style for this run (`Concise`, `Proactive`, `Explanatory`, `Learning`, or `default` for none); overrides `general.outputStyle` | `qwen -p "query" --output-style Concise` |
| `--debug`, `-d` | Enable debug mode | `qwen -p "query" --debug` |
| `--safe-mode` | Disable all customizations — context files, hooks, extensions, skills, MCP servers, custom subagents (only built-in subagents load), permission rules, settings-sourced approval mode overrides, memory features, and sandbox settings — to isolate problems; the CLI flags `--yolo` and `--approval-mode` still take effect. See [Troubleshooting](../support/troubleshooting). Also settable via `QWEN_CODE_SAFE_MODE=true`. | `qwen -p "query" --safe-mode` |
| `--model`, `-m` | Model to use for this run | `qwen -p "query" --model qwen3-coder-plus` |
Expand Down
Loading
Loading