# Filesystem

Use the filesystem API to read, change, and search files in a sandbox without constructing shell commands.

## Read and write files

Read and update a Laravel view:

```ts
const view = await sandbox.files.readText('resources/views/welcome.blade.php');

await sandbox.files.write(
  'resources/views/welcome.blade.php',
  view.replace('Laravel', 'Inventory'),
);
```

Use `read()` for binary data, `readLines()` for part of a text file, and `readStream()` for a large download. `write()` accepts text, binary, and stream content.

## Manage files and directories

```ts
await sandbox.files.createDirectory('storage/imports');
await sandbox.files.copy('fixtures/customers.csv', 'storage/imports/customers.csv');
await sandbox.files.move('storage/imports/customers.csv', 'storage/imports/pending.csv');

const entries = await sandbox.files.list('storage/imports');
const tree = await sandbox.files.tree('storage');

console.log(entries, tree);
```

Use `stat()` to inspect an entry and `exists()` when a missing path is an expected outcome. `remove()` changes the sandbox immediately.

## Find names and search content

`find()` searches paths. `search()` searches file contents and returns whether its result limit was reached alongside the matches:

```ts
const routeFiles = await sandbox.files.find('*.php', {
  includes: ['routes/**'],
});

const [limitHit, matches] = await sandbox.files.search(
  { pattern: 'Route::' },
  {
    includes: ['**/*.php'],
    excludes: ['vendor/**'],
  },
);

console.log({ routeFiles, limitHit, matches });
```

## Watch a path

Filesystem watches require the realtime transport. Creating a watch is asynchronous:

```ts
const watcher = await sandbox.files.watch(
  '/app',
  { recursive: true, excludes: ['vendor/**', 'node_modules/**'] },
  (change) => console.log(change.type, change.path),
);

```

File watches require the realtime client. REST clients can read, write, and search, but cannot receive filesystem events. Use `follow()` when appended content matters, such as a Laravel log.

Use [Commands and processes](/docs/sdk/processes) when the operation belongs to a build tool or framework command rather than direct file manipulation.