Single-Turn Query Example

Simple single-turn queries with the SDK

Single-turn queries are the simplest way to use the SDK. You send one prompt and get a response, similar to using a chat interface.

Basic Single-Turn Query

import { query } from '@qwen-code/sdk';

const result = query({
  prompt: 'What files are in the current directory?',
  options: {
    cwd: process.cwd(),
  },
});

for await (const message of result) {
  if (message.type === 'assistant') {
    console.log('Assistant:', message.message.content);
  } else if (message.type === 'result') {
    console.log('Result:', message.result);
  }
}

With Permission Control

Allow only read operations:

import { query } from '@qwen-code/sdk';

const result = query({
  prompt: 'Read the package.json file and tell me the project name',
  options: {
    cwd: process.cwd(),
    permissionMode: 'default',
    canUseTool: async (toolName, input) => {
      // Allow all read operations
      if (toolName.startsWith('read_') || toolName === 'list_directory') {
        return { behavior: 'allow', updatedInput: input };
      }
      
      // Deny everything else
      return {
        behavior: 'deny',
        message: `${toolName} is not allowed`,
      };
    },
  },
});

for await (const message of result) {
  if (message.type === 'assistant') {
    console.log(message.message.content);
  }
}

With Specific Model

import { query } from '@qwen-code/sdk';

const result = query({
  prompt: 'Explain how async/await works in JavaScript',
  options: {
    model: 'gpt-4',
    permissionMode: 'plan', // Just explanation, no execution
  },
});

for await (const message of result) {
  if (message.type === 'assistant') {
    for (const block of message.message.content) {
      if (block.type === 'text') {
        console.log(block.text);
      }
    }
  }
}

Processing All Message Types

import {
  query,
  isSDKAssistantMessage,
  isSDKResultMessage,
  isSDKSystemMessage,
} from '@qwen-code/sdk';

const result = query({
  prompt: 'List TypeScript files in the src directory',
  options: {
    cwd: process.cwd(),
    permissionMode: 'default',
    allowedTools: ['list_directory', 'list_files'],
  },
});

for await (const message of result) {
  if (isSDKSystemMessage(message)) {
    console.log('--- System Info ---');
    console.log('Session ID:', message.session_id);
    console.log('Working directory:', message.cwd);
    console.log('Model:', message.model);
    console.log('Permission mode:', message.permission_mode);
  } else if (isSDKAssistantMessage(message)) {
    console.log('\n--- Assistant Response ---');
    for (const block of message.message.content) {
      if (block.type === 'text') {
        console.log(block.text);
      } else if (block.type === 'tool_use') {
        console.log(`[Tool: ${block.name}]`);
      }
    }
  } else if (isSDKResultMessage(message)) {
    console.log('\n--- Final Result ---');
    if (message.is_error) {
      console.error('Error:', message.error);
    } else {
      console.log('Success:', message.result);
    }
    console.log(`Duration: ${message.duration_ms}ms`);
    console.log(`Turns: ${message.num_turns}`);
    console.log(`Tokens: ${message.usage.input_tokens + message.usage.output_tokens}`);
  }
}

With YOLO Mode

YOLO mode allows all operations. Use only in trusted environments.

import { query } from '@qwen-code/sdk';

const result = query({
  prompt: 'Create a hello.txt file with "Hello, World!"',
  options: {
    cwd: '/tmp/test-project',
    permissionMode: 'yolo',
  },
});

for await (const message of result) {
  if (message.type === 'result') {
    console.log('Done!', message.result);
  }
}

With Error Handling

import { query, isAbortError } from '@qwen-code/sdk';

async function runQuery() {
  try {
    const result = query({
      prompt: 'Analyze the codebase',
      options: {
        cwd: process.cwd(),
      },
    });

    for await (const message of result) {
      if (message.type === 'assistant') {
        console.log(message.message.content);
      } else if (message.type === 'result') {
        if (message.is_error) {
          console.error('Query failed:', message.error);
        } else {
          console.log('Success:', message.result);
        }
      }
    }
  } catch (error) {
    if (isAbortError(error)) {
      console.log('Query was aborted');
    } else {
      console.error('Unexpected error:', error);
    }
  }
}

runQuery().catch(console.error);

Collecting All Responses

import { query, isSDKAssistantMessage } from '@qwen-code/sdk';

async function getAllResponses(prompt: string): Promise<string[]> {
  const responses: string[] = [];
  
  const result = query({
    prompt,
    options: {},
  });

  for await (const message of result) {
    if (isSDKAssistantMessage(message)) {
      for (const block of message.message.content) {
        if (block.type === 'text') {
          responses.push(block.text);
        }
      }
    }
  }
  
  return responses;
}

const responses = await getAllResponses('What is the capital of France?');
console.log('All responses:', responses);

With Session ID Tracking

import { query } from '@qwen-code/sdk';

const sessionId = '123e4567-e89b-12d3-a456-426614174000';

const result = query({
  prompt: 'Hello, remember this session',
  options: {
    sessionId,  // Use specific session ID
  },
});

console.log('Session ID:', result.getSessionId());
// Output: Session ID: 123e4567-e89b-12d3-a456-426614174000

for await (const message of result) {
  if (message.type === 'result') {
    console.log('You can resume this session later with:', sessionId);
  }
}

With Custom Error Handler

import { query } from '@qwen-code/sdk';

const result = query({
  prompt: 'Analyze the project',
  options: {
    cwd: process.cwd(),
    stderr: (message) => {
      console.error('[CLI Error]:', message);
    },
    debug: true,
    logLevel: 'debug',
  },
});

for await (const message of result) {
  console.log(message);
}

See Also

• Multi-Turn Example - Multi-turn conversations
• Permission Modes - Permission control
• Message Types - Understanding messages