File Listing

Explore files and directories in your sandbox with detailed metadata and flexible filtering options.

Basic Listing

const result = await sandbox.files.list({
  dirPath: '/opt/app'
});

result.files.forEach(file => {
  console.log(`${file.type}: ${file.name} (${file.size} bytes)`);
});

const response = await fetch(`${sandbox.url}/files/list`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dirPath: '/opt/app'
  })
});

const result = await response.json();

curl -X POST https://sandbox.oblien.com/files/list \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dirPath": "/opt/app"
  }'

Response:

{
  "success": true,
  "files": [
    {
      "name": "src",
      "path": "/opt/app/src",
      "type": "directory",
      "size": 4096,
      "modified": "2025-10-26T12:00:00Z"
    },
    {
      "name": "package.json",
      "path": "/opt/app/package.json",
      "type": "file",
      "size": 1245,
      "modified": "2025-10-26T11:30:00Z"
    }
  ],
  "path": "/opt/app",
  "total": 2
}

File Metadata

Each file entry includes:

Field	Type	Description
`name`	string	File or directory name
`path`	string	Full absolute path
`type`	string	`"file"` or `"directory"`
`size`	number	Size in bytes
`modified`	string	Last modified timestamp (ISO 8601)

Listing Options

Recursive Listing

List all files including subdirectories:

const result = await sandbox.files.list({
  dirPath: '/opt/app',
  recursive: true
});

Ignore Patterns

Exclude files and directories by pattern:

const result = await sandbox.files.list({
  dirPath: '/opt/app',
  recursive: true,
  ignorePatterns: ['node_modules', '.git', 'dist', '*.log']
});

Nested Structure

Get a nested directory tree:

const result = await sandbox.files.list({
  dirPath: '/opt/app',
  recursive: true,
  nested: true
});

// Returns hierarchical structure

Light Mode

Get minimal information (faster for large directories):

const result = await sandbox.files.list({
  dirPath: '/opt/app',
  light: true
});

Use .gitignore

Respect .gitignore patterns:

const result = await sandbox.files.list({
  dirPath: '/opt/app',
  recursive: true,
  useGitignore: true
});

Path Filter

Filter results by path substring:

const result = await sandbox.files.list({
  dirPath: '/opt/app',
  recursive: true,
  pathFilter: 'component'
});

// Only returns paths containing 'component'

Include File Hash

Include file content hash:

const result = await sandbox.files.list({
  dirPath: '/opt/app',
  includeHash: true
});

Include Content

Include file content in listing:

const result = await sandbox.files.list({
  dirPath: '/opt/app',
  includeContent: true,
  maxContentSize: 1000000 // 1MB max
});

Complete Example

const result = await sandbox.files.list({
  dirPath: '/opt/app/src',
  recursive: true,
  ignorePatterns: ['node_modules', '*.test.js'],
  useGitignore: true,
  pathFilter: 'component'
});

console.log(`Found ${result.total} files`);
result.files.forEach(file => {
  if (file.type === 'file') {
    console.log(`  ${file.path}`);
  }
});

const response = await fetch(`${sandbox.url}/files/list`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dirPath: '/opt/app/src',
    recursive: true,
    ignorePatterns: ['node_modules', '*.test.js'],
    useGitignore: true,
    pathFilter: 'component'
  })
});

const result = await response.json();

curl -X POST https://sandbox.oblien.com/files/list \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

All Parameters

Parameter	Type	Default	Description
`dirPath`	string	required	Directory to list
`recursive`	boolean	false	Include subdirectories
`ignorePatterns`	string[]	[]	Patterns to ignore
`nested`	boolean	false	Return nested structure
`light`	boolean	false	Minimal info only
`flattenResults`	boolean	true	Flatten nested results
`maxDepth`	number	unlimited	Max recursion depth
`useGitignore`	boolean	false	Respect .gitignore
`pathFilter`	string	-	Filter by path substring
`includeHash`	boolean	false	Include file hash
`includeContent`	boolean	false	Include file content
`maxContentSize`	number	1MB	Max content size

Best Practices

Use ignore patterns for large directories:

ignorePatterns: ['node_modules', '.git', 'dist']

Enable light mode for performance: Use light: true when you only need paths
Respect .gitignore: Set useGitignore: true to skip ignored files
Limit recursion depth: Use maxDepth for deep directory trees

Next Steps

File Reading - Read file contents
File Writing - Create and edit files
File Operations - All file operations

On this page