mirror of
https://github.com/QwenLM/qwen-code.git
synced 2025-12-19 09:33:53 +00:00
309 lines
8.9 KiB
Markdown
309 lines
8.9 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)
|
|
- [Response Schema](#response-schema)
|
|
- [Example Usage](#example-usage)
|
|
- [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)
|
|
- [Code review](#code-review-1)
|
|
- [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
|
|
|
|
### 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 including response, statistics, and metadata. This
|
|
format is ideal for programmatic processing and automation scripts.
|
|
|
|
#### Response Schema
|
|
|
|
The JSON output follows this high-level structure:
|
|
|
|
```json
|
|
{
|
|
"response": "string", // The main AI-generated content answering your prompt
|
|
"stats": {
|
|
// Usage metrics and performance data
|
|
"models": {
|
|
// Per-model API and token usage statistics
|
|
"[model-name]": {
|
|
"api": {
|
|
/* request counts, errors, latency */
|
|
},
|
|
"tokens": {
|
|
/* prompt, response, cached, total counts */
|
|
}
|
|
}
|
|
},
|
|
"tools": {
|
|
// Tool execution statistics
|
|
"totalCalls": "number",
|
|
"totalSuccess": "number",
|
|
"totalFail": "number",
|
|
"totalDurationMs": "number",
|
|
"totalDecisions": {
|
|
/* accept, reject, modify, auto_accept counts */
|
|
},
|
|
"byName": {
|
|
/* per-tool detailed stats */
|
|
}
|
|
},
|
|
"files": {
|
|
// File modification statistics
|
|
"totalLinesAdded": "number",
|
|
"totalLinesRemoved": "number"
|
|
}
|
|
},
|
|
"error": {
|
|
// Present only when an error occurred
|
|
"type": "string", // Error type (e.g., "ApiError", "AuthError")
|
|
"message": "string", // Human-readable error description
|
|
"code": "number" // Optional error code
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Example Usage
|
|
|
|
```bash
|
|
qwen -p "What is the capital of France?" --output-format json
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"response": "The capital of France is Paris.",
|
|
"stats": {
|
|
"models": {
|
|
"qwen3-coder-plus": {
|
|
"api": {
|
|
"totalRequests": 2,
|
|
"totalErrors": 0,
|
|
"totalLatencyMs": 5053
|
|
},
|
|
"tokens": {
|
|
"prompt": 24939,
|
|
"candidates": 20,
|
|
"total": 25113,
|
|
"cached": 21263,
|
|
"thoughts": 154,
|
|
"tool": 0
|
|
}
|
|
}
|
|
},
|
|
"tools": {
|
|
"totalCalls": 1,
|
|
"totalSuccess": 1,
|
|
"totalFail": 0,
|
|
"totalDurationMs": 1881,
|
|
"totalDecisions": {
|
|
"accept": 0,
|
|
"reject": 0,
|
|
"modify": 0,
|
|
"auto_accept": 1
|
|
},
|
|
"byName": {
|
|
"google_web_search": {
|
|
"count": 1,
|
|
"success": 1,
|
|
"fail": 0,
|
|
"durationMs": 1881,
|
|
"decisions": {
|
|
"accept": 0,
|
|
"reject": 0,
|
|
"modify": 0,
|
|
"auto_accept": 1
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"files": {
|
|
"totalLinesAdded": 0,
|
|
"totalLinesRemoved": 0
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 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"
|
|
```
|
|
|
|
## Configuration Options
|
|
|
|
Key command-line options for headless usage:
|
|
|
|
| Option | Description | Example |
|
|
| ----------------------- | ---------------------------------- | ------------------------------------------------ |
|
|
| `--prompt`, `-p` | Run in headless mode | `qwen -p "query"` |
|
|
| `--output-format` | Specify output format (text, json) | `qwen -p "query" --output-format json` |
|
|
| `--model`, `-m` | Specify the Qwen model | `qwen -p "query" -m qwen3-coder-plus` |
|
|
| `--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
|
|
```
|
|
|
|
#### 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
|