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.

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:


qwen --prompt "What is machine learning?"

Stdin Input

Pipe input to Qwen Code from your terminal:


echo "Explain this code" | qwen

Combining with File Input

Read from files and process with Qwen Code:


cat README.md | qwen --prompt "Summarize this documentation"

Output Formats

Text Output (Default)

Standard human-readable output:


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:


{
  "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


qwen -p "What is the capital of France?" --output-format json

Response:


{
  "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:


# 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.

Examples

Code review


cat src/auth.py | qwen -p "Review this authentication code for security issues" > security-review.txt

Generate commit messages


result=$(git diff --cached | qwen -p "Write a concise commit message for these changes" --output-format json)
echo "$result" | jq -r '.response'

API documentation


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


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


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


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


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


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 - Complete configuration guide
Authentication - Setup authentication
Commands - Interactive commands reference
Tutorials - Step-by-step automation guides