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

# --session-id Option

> Specify a custom identifier for your session

## Overview

The `--session-id` option allows you to specify a custom identifier for your Qwen Code session. This makes it easier to organize, track, and resume specific conversations, especially for long-running projects or specific features.

## Syntax

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

## Basic Usage

### Create Named Session

```bash theme={null}
qwen --session-id feature-authentication
```

This creates a session with ID `feature-authentication` instead of a random UUID.

### Resume Named Session

```bash theme={null}
# Later, resume by name
qwen --resume feature-authentication
```

Much easier than remembering `a1b2c3d4-e5f6-7890-abcd-ef1234567890`!

## Benefits

### Easy Identification

```bash theme={null}
# Random IDs (hard to remember)
qwen
Session ID: f3d2e1c4-b5a6-7890-dcba-ef1234567890

# Named IDs (easy to remember)
qwen --session-id fix-login-bug
Session ID: fix-login-bug
```

### Organized Workflows

```bash theme={null}
# Organize by feature
qwen --session-id feature-notifications
qwen --session-id feature-payments
qwen --session-id feature-analytics

# Organize by task type
qwen --session-id refactor-auth-module
qwen --session-id add-unit-tests
qwen --session-id update-dependencies
```

### Team Collaboration

```bash theme={null}
# Shared session names
qwen --session-id sprint-23-api-work
qwen --session-id hotfix-prod-issue-456
qwen --session-id onboarding-new-dev
```

### CI/CD Integration

```bash theme={null}
# Predictable session IDs
qwen --session-id "ci-build-${BUILD_NUMBER}"
qwen --session-id "pr-${PR_NUMBER}-review"
```

## Naming Conventions

### By Feature

```bash theme={null}
qwen --session-id feature-user-profiles
qwen --session-id feature-social-login
qwen --session-id feature-email-notifications
```

### By Bug Number

```bash theme={null}
qwen --session-id bug-123-memory-leak
qwen --session-id bug-456-cors-error
qwen --session-id hotfix-789-crash
```

### By Task

```bash theme={null}
qwen --session-id refactor-database-layer
qwen --session-id migrate-to-typescript
qwen --session-id add-api-documentation
```

### By Date

```bash theme={null}
qwen --session-id "2024-03-10-sprint-planning"
qwen --session-id "2024-03-11-code-review"
qwen --session-id "2024-03-12-bug-fixing"
```

### By Project Phase

```bash theme={null}
qwen --session-id mvp-development
qwen --session-id beta-testing-fixes
qwen --session-id production-optimization
```

## Use Cases

### Feature Development

```bash theme={null}
# Start feature work
qwen --session-id feature-oauth
> Implement OAuth authentication

# Next day, continue
qwen --resume feature-oauth
> Add OAuth providers

# Days later, finalize
qwen --resume feature-oauth
> Write tests for OAuth
```

### Bug Fixing

```bash theme={null}
# Track bug investigation
qwen --session-id bug-401-login-fails
> Investigate login failure

# Continue investigation
qwen --resume bug-401-login-fails
> Test potential fixes

# Implement fix
qwen --resume bug-401-login-fails
> Implement the fix
```

### Code Reviews

```bash theme={null}
# Review PR
qwen --session-id pr-123-review
> Review changes in PR #123

# Follow-up
qwen --resume pr-123-review
> Check if feedback was addressed
```

### Learning Sessions

```bash theme={null}
# Learning new tech
qwen --session-id learning-graphql
> Help me learn GraphQL

# Continue learning
qwen --resume learning-graphql
> Now explain GraphQL subscriptions
```

## Session Validation

### Valid Session IDs

✅ Alphanumeric characters: `feature-auth`\
✅ Hyphens: `fix-bug-123`\
✅ Underscores: `feature_oauth`\
✅ UUIDs: `a1b2c3d4-e5f6-7890-abcd-ef1234567890`

### Invalid Session IDs

❌ Spaces: `feature auth` (use `feature-auth`)\
❌ Special chars: `feature@auth` (use `feature-auth`)\
❌ Empty string: `""` (must provide ID)

### Validation Rules

```bash theme={null}
# Valid
qwen --session-id feature-123
qwen --session-id ABC_def_456
qwen --session-id my-cool-feature

# Invalid (will show error)
qwen --session-id "my feature"  # Spaces not allowed
qwen --session-id "feature@123"  # @ not allowed
```

## Combining with Other Options

### With Prompts

```bash theme={null}
qwen --session-id task-123 --prompt "Start implementing feature"
```

### With YOLO Mode

```bash theme={null}
qwen --session-id automated-fixes --yolo --prompt "Fix all linting errors"
```

### With Models

```bash theme={null}
qwen --session-id complex-refactor --model qwen-coder-plus
```

### With Output Format

```bash theme={null}
qwen --session-id ci-build --prompt "Run tests" --output-format json
```

## Session Persistence

Sessions with custom IDs are stored in:

```
~/.qwen/sessions/<project-hash>/
  ├── feature-auth.json
  ├── bug-123.json
  └── refactor-db.json
```

### List Your Sessions

```bash theme={null}
# View all session IDs
ls ~/.qwen/sessions/<project-hash>/

# Or use resume picker
qwen --resume
```

### Session Metadata

```bash theme={null}
# View session info
cat ~/.qwen/sessions/<project-hash>/feature-auth.json | jq '{
  sessionId,
  startTime,
  messageCount: (.messages | length),
  totalTokens: .usage.totalTokens
}'
```

## Automation Examples

### CI/CD Build Session

```yaml theme={null}
# .github/workflows/ai-review.yml
name: AI Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: AI Review
        env:
          DASHSCOPE_API_KEY: ${{ secrets.DASHSCOPE_API_KEY }}
        run: |
          qwen --session-id "pr-${{ github.event.pull_request.number }}" \
               --prompt "Review the changes" \
               --output-format json
```

### Daily Standup

```bash theme={null}
#!/bin/bash
# daily-standup.sh

DATE=$(date +%Y-%m-%d)
SESSION="standup-$DATE"

qwen --session-id "$SESSION" --prompt "
Review git commits from today and summarize:
- What was accomplished
- What's in progress  
- Any blockers
"
```

### Feature Tracking

```bash theme={null}
#!/bin/bash
# track-feature.sh

FEATURE_NAME=$1
SESSION="feature-${FEATURE_NAME}"

qwen --session-id "$SESSION" --prompt "
Track progress on feature: $FEATURE_NAME
- List completed tasks
- List remaining tasks
- Estimate completion
"
```

### Test Session

```bash theme={null}
# Create test session
qwen --session-id test-session --sandbox

# Experiment safely
> Try risky operations

# Don't worry about breaking things
# It's isolated in the test session
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Descriptive Names">
    Make session IDs self-explanatory:

    ```bash theme={null}
    # Bad
    qwen --session-id s1
    qwen --session-id temp
    qwen --session-id test

    # Good
    qwen --session-id implement-user-auth
    qwen --session-id fix-payment-bug
    qwen --session-id refactor-api-layer
    ```
  </Accordion>

  <Accordion title="Follow Naming Convention">
    Be consistent across your team:

    ```bash theme={null}
    # Team convention: type-description-number
    qwen --session-id feature-oauth-123
    qwen --session-id bug-login-456
    qwen --session-id refactor-db-789
    ```
  </Accordion>

  <Accordion title="Keep IDs Short But Clear">
    Balance brevity with clarity:

    ```bash theme={null}
    # Too long
    qwen --session-id implement-the-new-user-authentication-system-with-oauth

    # Too short
    qwen --session-id auth

    # Just right
    qwen --session-id feature-oauth-auth
    ```
  </Accordion>

  <Accordion title="Include Context">
    Add relevant context to IDs:

    ```bash theme={null}
    # Include issue number
    qwen --session-id bug-gh-123

    # Include date for time-sensitive tasks
    qwen --session-id hotfix-2024-03-10

    # Include sprint for sprint work
    qwen --session-id sprint-23-api
    ```
  </Accordion>
</AccordionGroup>

## Session ID vs Resume

### Use --session-id When:

✅ **Creating a new session** with a specific name\
✅ **You know the name** you want to use\
✅ **Organizing work** by feature or task\
✅ **CI/CD** and automation

### Use --resume When:

✅ **Continuing existing session**\
✅ **Don't remember the exact ID**\
✅ **Want to browse** available sessions

### Example Workflow

```bash theme={null}
# Day 1: Create named session
qwen --session-id feature-notifications
> Implement notification system

# Day 2: Resume by name
qwen --resume feature-notifications
> Continue with email notifications

# Day 3: Resume by name
qwen --resume feature-notifications
> Add push notifications
```

## Troubleshooting

### Session ID Already Exists

If you use an existing session ID:

```bash theme={null}
qwen --session-id feature-auth
# Continues existing 'feature-auth' session
```

To start fresh:

```bash theme={null}
# Delete old session
rm ~/.qwen/sessions/<project-hash>/feature-auth.json

# Start new session
qwen --session-id feature-auth
```

### Invalid Session ID Format

```
Error: Invalid session ID format
```

**Solution:**

```bash theme={null}
# Fix special characters
qwen --session-id "feature@auth"  # ❌
qwen --session-id "feature-auth"   # ✅

# Remove spaces
qwen --session-id "feature auth"   # ❌
qwen --session-id "feature-auth"   # ✅
```

### Can't Find Custom Session

If you can't find your named session:

```bash theme={null}
# List all sessions
ls ~/.qwen/sessions/<project-hash>/

# Search for session
find ~/.qwen/sessions -name '*feature*'

# Use session picker
qwen --resume
```

## Advanced Usage

### Dynamic Session IDs

```bash theme={null}
#!/bin/bash
# Generate session IDs dynamically

BRANCH=$(git branch --show-current)
qwen --session-id "work-${BRANCH}"

# Automatically ties sessions to Git branches
```

### Session Templates

```bash theme={null}
#!/bin/bash
# Create session from template

TEMPLATE=$1
NAME=$2

case $TEMPLATE in
  feature)
    qwen --session-id "feature-${NAME}"
    ;;
  bug)
    qwen --session-id "bug-${NAME}"
    ;;
  refactor)
    qwen --session-id "refactor-${NAME}"
    ;;
esac

# Usage: ./create-session.sh feature oauth
```

### Session Namespaces

```bash theme={null}
# Organize by namespace
qwen --session-id "frontend:feature-ui"
qwen --session-id "backend:feature-api"
qwen --session-id "infra:setup-ci"

# Easy to filter
ls ~/.qwen/sessions/<project-hash>/ | grep frontend:
```

## See Also

<CardGroup cols={2}>
  <Card title="--resume Option" icon="clock-rotate-left" href="/cli/options/resume">
    Resume previous sessions
  </Card>

  <Card title="--continue Option" icon="play" href="/cli/options/continue">
    Continue most recent session
  </Card>

  <Card title="Session Management" icon="clock" href="/features/sessions">
    Complete guide to sessions
  </Card>

  <Card title="Workflow Organization" icon="diagram-project" href="/advanced/workflows">
    Organizing your AI workflow
  </Card>
</CardGroup>