Search

Fast search capabilities for finding files and content in your sandbox environment.

Search File Contents

Search for text within files.

// Using SDK
const results = await sandbox.search({
  query: 'function handleRequest',
  options: {
    caseSensitive: false,
    maxResults: 50,
    include: ['*.js', '*.ts'],
    exclude: ['node_modules/**', 'dist/**']
  }
});

results.matches.forEach(match => {
  console.log(`${match.file}:${match.line} - ${match.text}`);
});

POST /search HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "query": "function handleRequest",
  "options": {
    "caseSensitive": false,
    "maxResults": 50,
    "include": ["*.js", "*.ts"],
    "exclude": ["node_modules/**", "dist/**"]
  }
}

Response:

{
  "success": true,
  "matches": [
    {
      "file": "/opt/app/src/server.js",
      "line": 42,
      "column": 10,
      "text": "function handleRequest(req, res) {",
      "context": {
        "before": "// Request handler",
        "after": "  const body = req.body;"
      }
    }
  ],
  "total": 3,
  "duration": 45
}

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Search term or regex pattern
`options.caseSensitive`	boolean	No	Case-sensitive search
`options.maxResults`	number	No	Maximum results (default: 100)
`options.include`	array	No	Glob patterns to include
`options.exclude`	array	No	Glob patterns to exclude
`options.regex`	boolean	No	Treat query as regex
`options.wholeWord`	boolean	No	Match whole words only

Search File Names

Search for files by name (faster than content search).

// Using SDK
const files = await sandbox.search.filenames({
  query: 'config',
  options: {
    maxResults: 20,
    extension: '.json'
  }
});

POST /search/filenames HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "query": "config",
  "options": {
    "maxResults": 20,
    "extension": ".json"
  }
}

Response:

{
  "success": true,
  "files": [
    {
      "name": "config.json",
      "path": "/opt/app/config.json",
      "size": 256,
      "modified": "2025-10-16T10:00:00Z"
    },
    {
      "name": "webpack.config.js",
      "path": "/opt/app/webpack.config.js",
      "size": 1024,
      "modified": "2025-10-15T18:30:00Z"
    }
  ],
  "total": 2
}

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Filename search term
`options.maxResults`	number	No	Maximum results
`options.extension`	string	No	Filter by file extension
`options.caseSensitive`	boolean	No	Case-sensitive search

Search Examples

Find All TODOs

const todos = await sandbox.search({
  query: 'TODO:|FIXME:|XXX:',
  options: {
    regex: true,
    exclude: ['node_modules/**', '.git/**']
  }
});

console.log(`Found ${todos.total} TODO comments`);

Find Function Definitions

const functions = await sandbox.search({
  query: '^(function|const|let)\\s+\\w+\\s*=',
  options: {
    regex: true,
    include: ['*.js', '*.ts'],
    caseSensitive: false
  }
});

Find Import Statements

const imports = await sandbox.search({
  query: 'import.*from',
  options: {
    regex: true,
    include: ['src/**/*.js']
  }
});

Find Configuration Files

const configs = await sandbox.search.filenames({
  query: 'config',
  options: {
    extension: '.json'
  }
});

Find Environment Variables

const envVars = await sandbox.search({
  query: 'process\\.env\\.',
  options: {
    regex: true,
    include: ['src/**']
  }
});

Advanced Search

Search with Context

Get surrounding lines for context:

const results = await sandbox.search({
  query: 'createServer',
  options: {
    contextLines: 3 // Show 3 lines before/after
  }
});

results.matches.forEach(match => {
  console.log('Before:', match.context.before);
  console.log('Match:', match.text);
  console.log('After:', match.context.after);
});

Search Specific Directories

// Search only in src directory
const results = await sandbox.search({
  query: 'export default',
  options: {
    include: ['src/**'],
    exclude: ['src/tests/**']
  }
});

Case-Sensitive Search

// Find exact case matches
const results = await sandbox.search({
  query: 'UserController',
  options: {
    caseSensitive: true
  }
});

Performance Tips

1. Use Filename Search When Possible

// ✅ Faster - search by filename
await sandbox.search.filenames({ query: 'index' });

// ❌ Slower - search content
await sandbox.search({ query: 'index' });

2. Limit Search Scope

// ✅ Good - specific directory
await sandbox.search({
  query: 'function',
  options: {
    include: ['src/**']
  }
});

// ❌ Bad - searches everything
await sandbox.search({ query: 'function' });

3. Exclude Large Directories

await sandbox.search({
  query: 'searchTerm',
  options: {
    exclude: [
      'node_modules/**',
      'dist/**',
      'build/**',
      '.git/**',
      '*.log'
    ]
  }
});

4. Use maxResults

// Limit results for faster response
await sandbox.search({
  query: 'console.log',
  options: {
    maxResults: 10 // Stop after 10 matches
  }
});

Error Handling

try {
  const results = await sandbox.search({ query: 'test' });
} catch (error) {
  if (error.message.includes('Invalid regex')) {
    console.log('Invalid search pattern');
  } else if (error.message.includes('timeout')) {
    console.log('Search took too long');
  }
}

Next Steps

Execute commands with Terminal
Monitor changes with File Watcher
Manage files with File Operations

On this page