Description
Lists all files and directories in the specified path. Supports recursive listing and filtering of hidden files.
Method Signature
async listFiles(
path: string,
options?: { recursive?: boolean; includeHidden?: boolean }
): Promise<ListFilesResult>
Parameters
Absolute path to the directory to list
Optional configuration for the listing operationWhether to list files recursively in subdirectories
Whether to include hidden files (those starting with ’.’)
Returns
Result of the list operationWhether the listing was successful
Array of file and directory informationName of the file or directory
Absolute path to the file or directory
Path relative to the listed directory
type
'file' | 'directory' | 'symlink' | 'other'
Type of the entry
Size in bytes (0 for directories)
ISO 8601 timestamp of last modification
Unix file mode (e.g., ‘0644’)
File permissionsWhether the file is readable
Whether the file is writable
Whether the file is executable
Total number of files and directories found
ISO 8601 timestamp of when the operation completed
Exit code from the underlying list command (0 = success)
Examples
List files in a directory
const result = await sandbox.listFiles('/workspace');
console.log(`Found ${result.count} items`);
for (const file of result.files) {
console.log(`${file.name} (${file.type}) - ${file.size} bytes`);
}
Recursive listing
const result = await sandbox.listFiles('/workspace', {
recursive: true
});
// Find all Python files
const pythonFiles = result.files.filter(
file => file.type === 'file' && file.name.endsWith('.py')
);
console.log(`Found ${pythonFiles.length} Python files`);
Include hidden files
const result = await sandbox.listFiles('/workspace', {
includeHidden: true
});
// Find .git directory
const gitDir = result.files.find(
file => file.name === '.git' && file.type === 'directory'
);
Check file permissions
const result = await sandbox.listFiles('/workspace');
for (const file of result.files) {
if (file.type === 'file') {
console.log(`${file.name}:`);
console.log(` Readable: ${file.permissions.readable}`);
console.log(` Writable: ${file.permissions.writable}`);
console.log(` Executable: ${file.permissions.executable}`);
}
}
Calculate directory size
const result = await sandbox.listFiles('/workspace', {
recursive: true
});
const totalSize = result.files
.filter(f => f.type === 'file')
.reduce((sum, f) => sum + f.size, 0);
console.log(`Total size: ${totalSize} bytes`);
Error Handling
The method throws an error if:
- The directory does not exist
- The path is not a directory
- Insufficient permissions to read the directory
try {
const result = await sandbox.listFiles('/nonexistent');
} catch (error) {
console.error('Failed to list files:', error.message);
}
Notes
- Symbolic links are identified but not followed
- The
recursive option can be slow for large directory trees
- Hidden files (starting with ’.’) are excluded by default
See Also