Headless Mode

Overview

Headless mode allows you to run Qwen Code without the interactive UI, making it ideal for:

CI/CD pipelines
Automation scripts
Batch processing
Integration with other tools
Programmatic access

Headless mode executes a single prompt and exits, optionally outputting structured data.

Basic Usage

# Execute a prompt and exit
qwen --prompt "Fix all TypeScript errors in src/"

# Short form
qwen -p "Add unit tests for the auth module"

Output Formats

Text (Default)
JSON
Stream JSON

Human-readable text output:

qwen --prompt "List all TODO comments" --output text

Output:

I found 3 TODO comments in your codebase:

src/auth.ts:42 - TODO: Add rate limiting
src/db.ts:156 - TODO: Implement connection pooling
tests/e2e.ts:23 - TODO: Add timeout handling

Structured JSON output:

qwen --prompt "Analyze this file" --output json

Output:

{
  "messages": [
    {
      "role": "system",
      "timestamp": "2026-03-10T20:00:00Z",
      "content": "Session initialized"
    },
    {
      "role": "user",
      "timestamp": "2026-03-10T20:00:01Z",
      "content": "Analyze this file"
    },
    {
      "role": "assistant",
      "timestamp": "2026-03-10T20:00:05Z",
      "content": "This file implements..."
    }
  ],
  "result": {
    "isError": false,
    "durationMs": 4523,
    "numTurns": 1,
    "usage": {
      "inputTokens": 1234,
      "outputTokens": 567
    }
  }
}

Streaming JSON for real-time processing:

qwen --prompt "Refactor this code" --output stream-json

Each line is a JSON event:

{"type":"system_message","timestamp":"...","content":"Session initialized"}
{"type":"user_message","timestamp":"...","content":"Refactor this code"}
{"type":"assistant_message_start","timestamp":"..."}
{"type":"content","value":"I'll refactor this code..."}
{"type":"tool_call","name":"edit","args":{"filePath":"..."}}
{"type":"tool_result","success":true}
{"type":"assistant_message_end"}
{"type":"result","isError":false,"durationMs":3421}

Input Formats

Standard Input

# Pipe content to qwen
cat requirements.txt | qwen --prompt "Create a project from these requirements"

# Use heredoc
qwen --prompt "Review this code" <<EOF
function add(a, b) {
  return a + b;
}
EOF

File Input

Use @include to reference files:

qwen --prompt "Fix bugs in @include(src/auth.ts)"

Stream JSON Input

For advanced integrations:

# Send structured input
qwen --input stream-json --output stream-json <<EOF
{"type":"user_message","content":"Analyze the codebase"}
EOF

Approval Modes in Headless

In headless mode with default approval, tools requiring approval will fail. Use yolo or auto-edit mode for automation.

YOLO Mode
Auto Edit Mode
Plan Mode

Auto-approve all actions:

qwen --prompt "Deploy to production" --approval-mode yolo

YOLO mode executes all actions without confirmation. Use with caution!

Auto-approve file edits only:

qwen --prompt "Refactor codebase" --approval-mode auto-edit

Shell commands still require approval (will fail in headless).

Analysis only, no modifications:

qwen --prompt "What needs fixing?" --approval-mode plan

AI analyzes but doesn’t execute tools that modify files or run commands.

Environment Variables

# Set API key
export GOOGLE_API_KEY="your-key-here"

# Configure model
export QWEN_MODEL="gemini-2.5-pro"

# Set working directory
export QWEN_WORKDIR="/path/to/project"

# Disable telemetry
export QWEN_TELEMETRY=false

# Set approval mode
export QWEN_APPROVAL_MODE=yolo

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Authentication error
`3`	Tool execution failed
`4`	Context limit exceeded
`5`	Invalid configuration

# Check exit code
qwen --prompt "Run tests"
if [ $? -eq 0 ]; then
  echo "Success"
else
  echo "Failed with code $?"
fi

Advanced Examples

CI/CD Integration

# .github/workflows/ai-review.yml
name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Qwen Code
        run: npm install -g @qwen-code/cli
      - name: Run AI Review
        env:
          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
        run: |
          qwen --prompt "Review changes in this PR" \
               --approval-mode plan \
               --output json > review.json
      - name: Post Comment
        run: gh pr comment --body-file review.json

Batch Processing

#!/bin/bash
# Process multiple files
for file in src/**/*.ts; do
  echo "Processing $file..."
  qwen --prompt "Add JSDoc comments to @include($file)" \
       --approval-mode auto-edit \
       --output text
done

Automation Script

#!/bin/bash
# Daily maintenance script

set -e

# Update dependencies
qwen -p "Update package.json dependencies to latest versions" --approval-mode yolo

# Run tests
qwen -p "Run the test suite and fix any failures" --approval-mode yolo

# Generate report
qwen -p "Create a summary of changes" --output json > daily-report.json

echo "Maintenance complete!"

Timeouts and Limits

# Set maximum session turns (default: 100)
qwen --prompt "Complex task" --max-turns 50

# Set operation timeout (in seconds)
timeout 300 qwen --prompt "Long-running analysis"

Debugging Headless Runs

# Enable debug output
DEBUG=qwen:* qwen --prompt "Debug this issue" 2> debug.log

# Verbose output
qwen --prompt "Analyze" --output json --verbose

# Save full session
qwen --prompt "Task" --output stream-json > session.jsonl

Error Handling

Shell Script
Python
Node.js

#!/bin/bash

if ! output=$(qwen --prompt "Fix bugs" --approval-mode yolo 2>&1); then
  echo "Qwen failed: $output" >&2
  # Send alert
  curl -X POST https://alerts.example.com \
    -d "{\"error\": \"$output\"}"
  exit 1
fi

echo "Success: $output"

import subprocess
import json

try:
    result = subprocess.run(
        ['qwen', '--prompt', 'Analyze code', '--output', 'json'],
        capture_output=True,
        text=True,
        check=True,
        timeout=300
    )
    data = json.loads(result.stdout)
    print(f"Success: {data['result']}")
except subprocess.CalledProcessError as e:
    print(f"Qwen failed with code {e.returncode}")
    print(f"Error: {e.stderr}")
except subprocess.TimeoutExpired:
    print("Qwen timed out after 5 minutes")

const { spawn } = require('child_process');

const qwen = spawn('qwen', [
  '--prompt', 'Generate tests',
  '--output', 'stream-json',
  '--approval-mode', 'yolo'
]);

let output = '';

qwen.stdout.on('data', (data) => {
  output += data.toString();
  // Process streaming JSON
  const lines = output.split('\n');
  for (const line of lines.slice(0, -1)) {
    try {
      const event = JSON.parse(line);
      console.log('Event:', event.type);
    } catch (e) {
      // Incomplete line
    }
  }
  output = lines[lines.length - 1];
});

qwen.on('close', (code) => {
  if (code === 0) {
    console.log('Success');
  } else {
    console.error(`Failed with code ${code}`);
  }
});

Limitations

No user input prompts

Tools that require user input (like ask_user_question) will fail in headless mode.Workaround: Use YOLO mode to skip confirmations, or provide input upfront.

Limited to single prompt

Each invocation processes one prompt. For multi-turn conversations, use interactive mode.Workaround: Chain multiple invocations or use the ACP protocol for stateful sessions.

No visual feedback

Progress indicators and rich formatting aren’t available.Workaround: Use stream-json output to implement your own progress tracking.

Session not persisted by default

Headless sessions aren’t saved to disk unless explicitly configured.Workaround: Use --save-session flag or export output to a file.

Best Practices

Always use --approval-mode yolo or auto-edit in automation
Set reasonable --max-turns to prevent infinite loops
Use --output stream-json for real-time processing
Implement proper error handling with exit codes
Set timeouts to prevent hanging processes
Log debug output for troubleshooting
Use environment variables for configuration
Test scripts locally before deploying to CI/CD

Next Steps

Approval Modes

Understand permission modes for automation

Session Commands

Learn available commands (some work in headless)

MCP Integration

Extend with Model Context Protocol servers

Interactive Mode

Switch to interactive UI for complex tasks

Getting Started

Core Features

Configuration

IDE Integration

Advanced

Overview

Basic Usage

Output Formats

Input Formats

Standard Input

File Input

Stream JSON Input

Approval Modes in Headless

Environment Variables

Exit Codes

Advanced Examples

CI/CD Integration

Batch Processing

Automation Script

Timeouts and Limits

Debugging Headless Runs

Error Handling

Limitations

Best Practices

Next Steps

Approval Modes

Session Commands

MCP Integration

Interactive Mode

Getting Started

Core Features

Configuration

IDE Integration

Advanced

​Overview

​Basic Usage

​Output Formats

​Input Formats

​Standard Input

​File Input

​Stream JSON Input

​Approval Modes in Headless

​Environment Variables

​Exit Codes

​Advanced Examples

​CI/CD Integration

​Batch Processing

​Automation Script

​Timeouts and Limits

​Debugging Headless Runs

​Error Handling

​Limitations

​Best Practices

​Next Steps

Approval Modes

Session Commands

MCP Integration

Interactive Mode

Overview

Basic Usage

Output Formats

Input Formats

Standard Input

File Input

Stream JSON Input

Approval Modes in Headless

Environment Variables

Exit Codes

Advanced Examples

CI/CD Integration

Batch Processing

Automation Script

Timeouts and Limits

Debugging Headless Runs

Error Handling

Limitations

Best Practices

Next Steps