Quick Start

Get started with Qwen Code in minutes

Get up and running with Qwen Code quickly. This guide will walk you through your first session and show you the essential features.

Before you begin: Make sure you’ve installed Qwen Code.

Start Your First Session

1. Launch Qwen Code

   Open your terminal and navigate to your project directory:

   cd your-project
   qwen
   

   On first launch, you’ll be prompted to authenticate. You can choose between:

   • Qwen OAuth (recommended): Free tier with 1,000 requests/day
   • API Key: Use OpenAI, Anthropic, Gemini, or other compatible providers

   If you’re in a CI/CD environment or SSH session where browser OAuth isn’t available, use the API key method instead.

2. Authenticate

   Run the auth command to set up your authentication:

   /auth
   

   For Qwen OAuth:

   1. Select “Qwen OAuth” from the menu
   2. A browser window will open
   3. Sign in with your qwen.ai account
   4. Return to the terminal - you’re ready to go!

   For API Key:

   1. Select “API Key” from the menu
   2. Choose your provider (OpenAI, Anthropic, Gemini, etc.)
   3. Enter your API key when prompted

   See the Authentication guide for detailed configuration options.

3. Try Your First Prompt

   Now you’re ready to interact with Qwen Code! Try some of these prompts:

   What does this project do?
   

   Explain the codebase structure
   

   Help me refactor this function
   

   Generate unit tests for this module
   

   You can reference specific files using @filename syntax, like: “Explain @src/main.ts”

Essential Commands

Learn the key commands to navigate your Qwen Code session.

/help - Show all available commands

Display a list of all available commands and their descriptions.

/help

/clear - Clear conversation history

Start a fresh conversation while keeping your configuration.

/clear

/model - Switch AI model

Change to a different model mid-session.

/model

Select from your configured models or add a new one.

/stats - View session statistics

See token usage, costs, and other session metrics.

/stats

/exit or /quit - Exit Qwen Code

Save your session and exit the CLI.

/exit

Keyboard Shortcuts

Make your workflow faster with these keyboard shortcuts:

Shortcut	Action
Ctrl+C	Cancel current operation
Ctrl+D	Exit (on empty line)
Up/Down	Navigate command history

Headless Mode

Run Qwen Code in non-interactive mode for scripts and automation:

qwen -p "your question or task"

Example uses:

Quick Code Review

qwen -p "Review the code in src/ and suggest improvements"

qwen -p "Generate unit tests for @src/api/users.ts"

qwen -p "Create a README for this project"

See Headless Mode for more details.

Reference Files

You can reference specific files in your prompts using the @ syntax:

Explain @src/main.ts

Refactor @components/UserList.tsx to use hooks

Compare @old/api.ts with @new/api.ts

Common Use Cases

Code Explanation

Understand a function

What does the calculateTotal function in @src/utils/cart.ts do?

Explain the overall architecture of this project

Code Generation

Create a new feature

Create a user authentication system with JWT tokens

Generate comprehensive unit tests for @src/services/payment.ts

Debugging

Find bugs

Why is this error occurring in @src/api/products.ts?

Analyze performance bottlenecks in @src/utils/parser.ts

Refactoring

Modernize code

Refactor @src/legacy/utils.js to use ES6+ features

Restructure @src/components/ to follow best practices

Advanced Features

Once you’re comfortable with the basics, explore these powerful features:

Approval Modes

Control how Qwen Code executes commands with different permission levels

Subagents

Delegate complex tasks to specialized AI agents

Skills

Extend Qwen Code with reusable skill modules

MCP Integration

Connect to Model Context Protocol servers

Session Management

Save and Resume Sessions

Your session history is automatically saved. To resume a previous session:

qwen --resume <session-id>

List your recent sessions:

/stats

Clear History

If you want to start fresh while keeping your configuration:

/clear

Configuration

Customize Qwen Code to fit your workflow:

Model Selection

Set your preferred model in ~/.qwen/settings.json:

{
  "model": {
    "name": "qwen3-coder-plus"
  }
}

Or switch models on the fly:

/model

Approval Mode

Choose how Qwen Code handles command execution:

• Plan: Review plan before execution
• Default: Approve each command
• Auto-edit: Auto-approve file edits
• YOLO: Auto-approve everything

Set via command line:

qwen --yolo    # Auto-approve everything
qwen --plan    # Plan mode

Or change mid-session:

/approval-mode

Learn more in Approval Modes.

Troubleshooting

Authentication fails

If OAuth fails:

1. Make sure you have a browser available
2. Try clearing your credentials: rm -rf ~/.qwen/credentials
3. Use API key authentication instead in headless environments

For API key issues:

1. Verify your API key is correct
2. Check that the provider is properly configured
3. Ensure you have network access to the API endpoint

Command not found

If you get “qwen: command not found”:

1. Make sure you’ve installed Qwen Code globally
2. Restart your terminal after installation
3. Check that npm global bin is in your PATH

npm install -g @qwen-code/qwen-code

Slow responses

If responses are slow:

1. Check your internet connection
2. Try a different model (some are faster)
3. Use /compress to reduce context size
4. Check API service status for your provider

Unexpected behavior

If Qwen Code behaves unexpectedly:

1. Run /clear to reset context
2. Check approval mode settings
3. Verify your configuration in ~/.qwen/settings.json
4. Use /bug to report issues with system info

Next Steps

Explore Interactive Mode

Learn all the features of the interactive terminal UI

Configure Providers

Set up multiple AI providers and models

Integrate with Your IDE

Use Qwen Code inside VS Code, Zed, or JetBrains

Advanced Features

Explore subagents, skills, and more