Headless Mode

Running Qwen Code non-interactively for scripts and automation

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)

Human-readable text output:

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

Output:

I found 3 TODO comments in your codebase:

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

JSON

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
    }
  }
}

Stream JSON

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-approve all actions:

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

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

Auto Edit Mode

Auto-approve file edits only:

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

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

Plan Mode

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

#!/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"

Python

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

Node.js

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

1. Always use --approval-mode yolo or auto-edit in automation
2. Set reasonable --max-turns to prevent infinite loops
3. Use --output stream-json for real-time processing
4. Implement proper error handling with exit codes
5. Set timeouts to prevent hanging processes
6. Log debug output for troubleshooting
7. Use environment variables for configuration
8. 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