> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/QwenLM/qwen-code/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Note>
  **Before you begin**: Make sure you've [installed Qwen Code](/installation).
</Note>

## Start Your First Session

<Steps>
  <Step title="Launch Qwen Code">
    Open your terminal and navigate to your project directory:

    ```bash theme={null}
    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

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

  <Step title="Authenticate">
    Run the auth command to set up your authentication:

    ```bash theme={null}
    /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](/authentication) guide for detailed configuration options.
  </Step>

  <Step title="Try Your First Prompt">
    Now you're ready to interact with Qwen Code! Try some of these prompts:

    ```text theme={null}
    What does this project do?
    ```

    ```text theme={null}
    Explain the codebase structure
    ```

    ```text theme={null}
    Help me refactor this function
    ```

    ```text theme={null}
    Generate unit tests for this module
    ```

    <Info>
      You can reference specific files using `@filename` syntax, like: "Explain @src/main.ts"
    </Info>
  </Step>
</Steps>

## Essential Commands

Learn the key commands to navigate your Qwen Code session.

<AccordionGroup>
  <Accordion title="/help - Show all available commands">
    Display a list of all available commands and their descriptions.

    ```bash theme={null}
    /help
    ```
  </Accordion>

  <Accordion title="/clear - Clear conversation history">
    Start a fresh conversation while keeping your configuration.

    ```bash theme={null}
    /clear
    ```
  </Accordion>

  <Accordion title="/model - Switch AI model">
    Change to a different model mid-session.

    ```bash theme={null}
    /model
    ```

    Select from your configured models or add a new one.
  </Accordion>

  <Accordion title="/stats - View session statistics">
    See token usage, costs, and other session metrics.

    ```bash theme={null}
    /stats
    ```
  </Accordion>

  <Accordion title="/exit or /quit - Exit Qwen Code">
    Save your session and exit the CLI.

    ```bash theme={null}
    /exit
    ```
  </Accordion>
</AccordionGroup>

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

```bash theme={null}
qwen -p "your question or task"
```

Example uses:

<CodeGroup>
  ```bash Quick Code Review theme={null}
  qwen -p "Review the code in src/ and suggest improvements"
  ```

  ```bash Generate Tests theme={null}
  qwen -p "Generate unit tests for @src/api/users.ts"
  ```

  ```bash Documentation theme={null}
  qwen -p "Create a README for this project"
  ```
</CodeGroup>

See [Headless Mode](/features/headless-mode) for more details.

## Reference Files

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

```text theme={null}
Explain @src/main.ts
```

```text theme={null}
Refactor @components/UserList.tsx to use hooks
```

```text theme={null}
Compare @old/api.ts with @new/api.ts
```

## Common Use Cases

### Code Explanation

<CodeGroup>
  ```text Understand a function theme={null}
  What does the calculateTotal function in @src/utils/cart.ts do?
  ```

  ```text Understand architecture theme={null}
  Explain the overall architecture of this project
  ```
</CodeGroup>

### Code Generation

<CodeGroup>
  ```text Create a new feature theme={null}
  Create a user authentication system with JWT tokens
  ```

  ```text Generate tests theme={null}
  Generate comprehensive unit tests for @src/services/payment.ts
  ```
</CodeGroup>

### Debugging

<CodeGroup>
  ```text Find bugs theme={null}
  Why is this error occurring in @src/api/products.ts?
  ```

  ```text Performance issues theme={null}
  Analyze performance bottlenecks in @src/utils/parser.ts
  ```
</CodeGroup>

### Refactoring

<CodeGroup>
  ```text Modernize code theme={null}
  Refactor @src/legacy/utils.js to use ES6+ features
  ```

  ```text Improve structure theme={null}
  Restructure @src/components/ to follow best practices
  ```
</CodeGroup>

## Advanced Features

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

<CardGroup cols={2}>
  <Card title="Approval Modes" icon="shield-check" href="/features/approval-modes">
    Control how Qwen Code executes commands with different permission levels
  </Card>

  <Card title="Subagents" icon="users" href="/features/subagents">
    Delegate complex tasks to specialized AI agents
  </Card>

  <Card title="Skills" icon="graduation-cap" href="/features/skills">
    Extend Qwen Code with reusable skill modules
  </Card>

  <Card title="MCP Integration" icon="plug" href="/features/mcp">
    Connect to Model Context Protocol servers
  </Card>
</CardGroup>

## Session Management

### Save and Resume Sessions

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

```bash theme={null}
qwen --resume <session-id>
```

List your recent sessions:

```bash theme={null}
/stats
```

### Clear History

If you want to start fresh while keeping your configuration:

```bash theme={null}
/clear
```

## Configuration

Customize Qwen Code to fit your workflow:

### Model Selection

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

```json theme={null}
{
  "model": {
    "name": "qwen3-coder-plus"
  }
}
```

Or switch models on the fly:

```bash theme={null}
/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:

```bash theme={null}
qwen --yolo    # Auto-approve everything
qwen --plan    # Plan mode
```

Or change mid-session:

```bash theme={null}
/approval-mode
```

Learn more in [Approval Modes](/features/approval-modes).

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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

    ```bash theme={null}
    npm install -g @qwen-code/qwen-code
    ```
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Explore Interactive Mode" icon="terminal" href="/features/interactive-mode">
    Learn all the features of the interactive terminal UI
  </Card>

  <Card title="Configure Providers" icon="sliders" href="/configuration/model-providers">
    Set up multiple AI providers and models
  </Card>

  <Card title="Integrate with Your IDE" icon="window" href="/ide-integration/overview">
    Use Qwen Code inside VS Code, Zed, or JetBrains
  </Card>

  <Card title="Advanced Features" icon="sparkles" href="/features/subagents">
    Explore subagents, skills, and more
  </Card>
</CardGroup>