mirror of
https://github.com/QwenLM/qwen-code.git
synced 2025-12-19 09:33:53 +00:00
288 lines
9.8 KiB
Markdown
288 lines
9.8 KiB
Markdown
# Headless Mode
|
|
|
|
Headless mode allows you to run Qwen Code programmatically from command line
|
|
scripts and automation tools without any interactive UI. This is ideal for
|
|
scripting, automation, CI/CD pipelines, and building AI-powered tools.
|
|
|
|
- [Headless Mode](#headless-mode)
|
|
- [Overview](#overview)
|
|
- [Basic Usage](#basic-usage)
|
|
- [Direct Prompts](#direct-prompts)
|
|
- [Stdin Input](#stdin-input)
|
|
- [Combining with File Input](#combining-with-file-input)
|
|
- [Output Formats](#output-formats)
|
|
- [Text Output (Default)](#text-output-default)
|
|
- [JSON Output](#json-output)
|
|
- [Example Usage](#example-usage)
|
|
- [Stream-JSON Output](#stream-json-output)
|
|
- [Input Format](#input-format)
|
|
- [File Redirection](#file-redirection)
|
|
- [Configuration Options](#configuration-options)
|
|
- [Examples](#examples)
|
|
- [Code review](#code-review)
|
|
- [Generate commit messages](#generate-commit-messages)
|
|
- [API documentation](#api-documentation)
|
|
- [Batch code analysis](#batch-code-analysis)
|
|
- [PR code review](#pr-code-review)
|
|
- [Log analysis](#log-analysis)
|
|
- [Release notes generation](#release-notes-generation)
|
|
- [Model and tool usage tracking](#model-and-tool-usage-tracking)
|
|
- [Resources](#resources)
|
|
|
|
## Overview
|
|
|
|
The headless mode provides a headless interface to Qwen Code that:
|
|
|
|
- Accepts prompts via command line arguments or stdin
|
|
- Returns structured output (text or JSON)
|
|
- Supports file redirection and piping
|
|
- Enables automation and scripting workflows
|
|
- Provides consistent exit codes for error handling
|
|
|
|
## Basic Usage
|
|
|
|
### Direct Prompts
|
|
|
|
Use the `--prompt` (or `-p`) flag to run in headless mode:
|
|
|
|
```bash
|
|
qwen --prompt "What is machine learning?"
|
|
```
|
|
|
|
### Stdin Input
|
|
|
|
Pipe input to Qwen Code from your terminal:
|
|
|
|
```bash
|
|
echo "Explain this code" | qwen
|
|
```
|
|
|
|
### Combining with File Input
|
|
|
|
Read from files and process with Qwen Code:
|
|
|
|
```bash
|
|
cat README.md | qwen --prompt "Summarize this documentation"
|
|
```
|
|
|
|
## Output Formats
|
|
|
|
Qwen Code supports multiple output formats for different use cases:
|
|
|
|
### Text Output (Default)
|
|
|
|
Standard human-readable output:
|
|
|
|
```bash
|
|
qwen -p "What is the capital of France?"
|
|
```
|
|
|
|
Response format:
|
|
|
|
```
|
|
The capital of France is Paris.
|
|
```
|
|
|
|
### JSON Output
|
|
|
|
Returns structured data as a JSON array. All messages are buffered and output together when the session completes. This format is ideal for programmatic processing and automation scripts.
|
|
|
|
The JSON output is an array of message objects. The output includes multiple message types: system messages (session initialization), assistant messages (AI responses), and result messages (execution summary).
|
|
|
|
#### Example Usage
|
|
|
|
```bash
|
|
qwen -p "What is the capital of France?" --output-format json
|
|
```
|
|
|
|
Output (at end of execution):
|
|
|
|
```json
|
|
[
|
|
{
|
|
"type": "system",
|
|
"subtype": "session_start",
|
|
"uuid": "...",
|
|
"session_id": "...",
|
|
"model": "qwen3-coder-plus",
|
|
...
|
|
},
|
|
{
|
|
"type": "assistant",
|
|
"uuid": "...",
|
|
"session_id": "...",
|
|
"message": {
|
|
"id": "...",
|
|
"type": "message",
|
|
"role": "assistant",
|
|
"model": "qwen3-coder-plus",
|
|
"content": [
|
|
{
|
|
"type": "text",
|
|
"text": "The capital of France is Paris."
|
|
}
|
|
],
|
|
"usage": {...}
|
|
},
|
|
"parent_tool_use_id": null
|
|
},
|
|
{
|
|
"type": "result",
|
|
"subtype": "success",
|
|
"uuid": "...",
|
|
"session_id": "...",
|
|
"is_error": false,
|
|
"duration_ms": 1234,
|
|
"result": "The capital of France is Paris.",
|
|
"usage": {...}
|
|
}
|
|
]
|
|
```
|
|
|
|
### Stream-JSON Output
|
|
|
|
Stream-JSON format emits JSON messages immediately as they occur during execution, enabling real-time monitoring. This format uses line-delimited JSON where each message is a complete JSON object on a single line.
|
|
|
|
```bash
|
|
qwen -p "Explain TypeScript" --output-format stream-json
|
|
```
|
|
|
|
Output (streaming as events occur):
|
|
|
|
```json
|
|
{"type":"system","subtype":"session_start","uuid":"...","session_id":"..."}
|
|
{"type":"assistant","uuid":"...","session_id":"...","message":{...}}
|
|
{"type":"result","subtype":"success","uuid":"...","session_id":"..."}
|
|
```
|
|
|
|
When combined with `--include-partial-messages`, additional stream events are emitted in real-time (message_start, content_block_delta, etc.) for real-time UI updates.
|
|
|
|
```bash
|
|
qwen -p "Write a Python script" --output-format stream-json --include-partial-messages
|
|
```
|
|
|
|
### Input Format
|
|
|
|
The `--input-format` parameter controls how Qwen Code consumes input from standard input:
|
|
|
|
- **`text`** (default): Standard text input from stdin or command-line arguments
|
|
- **`stream-json`**: JSON message protocol via stdin for bidirectional communication
|
|
|
|
> **Note:** Stream-json input mode is currently under construction and is intended for SDK integration. It requires `--output-format stream-json` to be set.
|
|
|
|
### File Redirection
|
|
|
|
Save output to files or pipe to other commands:
|
|
|
|
```bash
|
|
# Save to file
|
|
qwen -p "Explain Docker" > docker-explanation.txt
|
|
qwen -p "Explain Docker" --output-format json > docker-explanation.json
|
|
|
|
# Append to file
|
|
qwen -p "Add more details" >> docker-explanation.txt
|
|
|
|
# Pipe to other tools
|
|
qwen -p "What is Kubernetes?" --output-format json | jq '.response'
|
|
qwen -p "Explain microservices" | wc -w
|
|
qwen -p "List programming languages" | grep -i "python"
|
|
|
|
# Stream-JSON output for real-time processing
|
|
qwen -p "Explain Docker" --output-format stream-json | jq '.type'
|
|
qwen -p "Write code" --output-format stream-json --include-partial-messages | jq '.event.type'
|
|
```
|
|
|
|
## Configuration Options
|
|
|
|
Key command-line options for headless usage:
|
|
|
|
| Option | Description | Example |
|
|
| ---------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------ |
|
|
| `--prompt`, `-p` | Run in headless mode | `qwen -p "query"` |
|
|
| `--output-format`, `-o` | Specify output format (text, json, stream-json) | `qwen -p "query" --output-format json` |
|
|
| `--input-format` | Specify input format (text, stream-json) | `qwen --input-format text --output-format stream-json` |
|
|
| `--include-partial-messages` | Include partial messages in stream-json output | `qwen -p "query" --output-format stream-json --include-partial-messages` |
|
|
| `--debug`, `-d` | Enable debug mode | `qwen -p "query" --debug` |
|
|
| `--all-files`, `-a` | Include all files in context | `qwen -p "query" --all-files` |
|
|
| `--include-directories` | Include additional directories | `qwen -p "query" --include-directories src,docs` |
|
|
| `--yolo`, `-y` | Auto-approve all actions | `qwen -p "query" --yolo` |
|
|
| `--approval-mode` | Set approval mode | `qwen -p "query" --approval-mode auto_edit` |
|
|
|
|
For complete details on all available configuration options, settings files, and environment variables, see the [Configuration Guide](./cli/configuration.md).
|
|
|
|
## Examples
|
|
|
|
### Code review
|
|
|
|
```bash
|
|
cat src/auth.py | qwen -p "Review this authentication code for security issues" > security-review.txt
|
|
```
|
|
|
|
### Generate commit messages
|
|
|
|
```bash
|
|
result=$(git diff --cached | qwen -p "Write a concise commit message for these changes" --output-format json)
|
|
echo "$result" | jq -r '.response'
|
|
```
|
|
|
|
### API documentation
|
|
|
|
```bash
|
|
result=$(cat api/routes.js | qwen -p "Generate OpenAPI spec for these routes" --output-format json)
|
|
echo "$result" | jq -r '.response' > openapi.json
|
|
```
|
|
|
|
### Batch code analysis
|
|
|
|
```bash
|
|
for file in src/*.py; do
|
|
echo "Analyzing $file..."
|
|
result=$(cat "$file" | qwen -p "Find potential bugs and suggest improvements" --output-format json)
|
|
echo "$result" | jq -r '.response' > "reports/$(basename "$file").analysis"
|
|
echo "Completed analysis for $(basename "$file")" >> reports/progress.log
|
|
done
|
|
```
|
|
|
|
### PR code review
|
|
|
|
```bash
|
|
result=$(git diff origin/main...HEAD | qwen -p "Review these changes for bugs, security issues, and code quality" --output-format json)
|
|
echo "$result" | jq -r '.response' > pr-review.json
|
|
```
|
|
|
|
### Log analysis
|
|
|
|
```bash
|
|
grep "ERROR" /var/log/app.log | tail -20 | qwen -p "Analyze these errors and suggest root cause and fixes" > error-analysis.txt
|
|
```
|
|
|
|
### Release notes generation
|
|
|
|
```bash
|
|
result=$(git log --oneline v1.0.0..HEAD | qwen -p "Generate release notes from these commits" --output-format json)
|
|
response=$(echo "$result" | jq -r '.response')
|
|
echo "$response"
|
|
echo "$response" >> CHANGELOG.md
|
|
```
|
|
|
|
### Model and tool usage tracking
|
|
|
|
```bash
|
|
result=$(qwen -p "Explain this database schema" --include-directories db --output-format json)
|
|
total_tokens=$(echo "$result" | jq -r '.stats.models // {} | to_entries | map(.value.tokens.total) | add // 0')
|
|
models_used=$(echo "$result" | jq -r '.stats.models // {} | keys | join(", ") | if . == "" then "none" else . end')
|
|
tool_calls=$(echo "$result" | jq -r '.stats.tools.totalCalls // 0')
|
|
tools_used=$(echo "$result" | jq -r '.stats.tools.byName // {} | keys | join(", ") | if . == "" then "none" else . end')
|
|
echo "$(date): $total_tokens tokens, $tool_calls tool calls ($tools_used) used with models: $models_used" >> usage.log
|
|
echo "$result" | jq -r '.response' > schema-docs.md
|
|
echo "Recent usage trends:"
|
|
tail -5 usage.log
|
|
```
|
|
|
|
## Resources
|
|
|
|
- [CLI Configuration](./cli/configuration.md) - Complete configuration guide
|
|
- [Authentication](./cli/authentication.md) - Setup authentication
|
|
- [Commands](./cli/commands.md) - Interactive commands reference
|
|
- [Tutorials](./cli/tutorials.md) - Step-by-step automation guides
|