> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript SDK: app file manager

> List, read, write, move and delete the files of an application with api.apps.files. Content travels as base64, so binary files round-trip byte for byte.

The file manager lives on `api.apps.files`. Every method takes the app id first, then a path inside the app. Paths are at most **256 characters**.

Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). `appId` is the id of one of your apps: [`api.account.me()`](/en/sdks/js/client#account) lists them.

## Listing a directory

`files.list(appId, path?)` lists a directory (the app root when `path` is omitted).

```typescript theme={"system"}
for (const entry of await api.apps.files.list(appId, "/src")) {
    console.log(entry.type, entry.name, entry.size, entry.lastModified);
}
```

| Field | Type | Description |
| - | - | - |
| `name` | `string` | Entry name |
| `type` | `"file" \| "directory"` | Entry kind |
| `size` | `number?` | Size in bytes. Absent on some directory entries |
| `lastModified` | `number \| null?` | Unix ms (may carry a fraction); `null` when unreadable |

A directory that does not exist is 404 `FILE_NOT_FOUND`. A path the file manager does not expose is 403 `BLOCKED_PATH`.

## Reading a file

`files.read(appId, path)` returns the file's bytes as a `Uint8Array`. Files are limited to **10 MB**: a larger one is 413 `FILE_TOO_LARGE`.

```typescript theme={"system"}
const bytes = await api.apps.files.read(appId, "/config.json");
const text = new TextDecoder().decode(bytes);

console.log(JSON.parse(text));
```

## Writing a file

`files.write(appId, path, content, { signal })` creates or overwrites a file.

* A `string` is sent as plain text.
* A `Uint8Array` is sent as base64, so any binary content round-trips.
* Empty content (`""` or empty bytes) creates an empty file.

```typescript theme={"system"}
// Text
await api.apps.files.write(appId, "/config.json", JSON.stringify({ debug: false }));

// Binary
const image = new Uint8Array(await (await fetch(imageUrl)).arrayBuffer());
await api.apps.files.write(appId, "/assets/logo.png", image);
```

Content over **10 MB** fails locally with `FILE_TOO_LARGE` (status `0`) before anything is sent. Content over **1 MiB** is sent without a timeout, like an upload: pass `{ signal }` to cancel it. For larger files, use [`apps.commit()`](/en/sdks/js/commit_and_upload).

<Note>
  Writing does not restart the app. Call [`apps.restart()`](/en/sdks/js/managing_application#start-stop-and-restart) to apply the change.
</Note>

## Moving or renaming a file

```typescript theme={"system"}
await api.apps.files.move(appId, "/config.json", "/config.old.json");
```

## Deleting a file

```typescript theme={"system"}
await api.apps.files.delete(appId, "/config.old.json");
```

## Errors

| Status | Code | When |
| - | - | - |
| 0 | `FILE_TOO_LARGE` | `write` content over 10 MB (checked locally) |
| 400 | `INVALID_PATH` | The path fails validation (traversal, invalid characters, too long), or `move` to the same path |
| 400 | `DELETE_FAILED`, `RENAME_FAILED` | The cluster could not delete or rename the file |
| 403 | `BLOCKED_PATH` | The path is not exposed by the file manager |
| 403 | `PERMISSION_DENIED` | Your workspace role cannot touch a restricted file (such as `.env`) |
| 404 | `FILE_NOT_FOUND` | The file or directory does not exist |
| 413 | `FILE_TOO_LARGE` | `read` of a file over 10 MB |
| 429 | `KEEP_CALM` | More than 10 writes in 5 seconds |

See [Errors](/en/sdks/js/errors) for the codes every call can return.

## Next steps

<CardGroup cols={3}>
  <Card title="Environment variables" icon="key" href="/en/sdks/js/environment_variables">
    Read and change the variables of an app.
  </Card>

  <Card title="File manager API reference" icon="code" href="/en/api-reference/endpoint/apps/filemanager/list">
    The REST endpoints behind these methods.
  </Card>

  <Card title="Manage files from the CLI" icon="terminal" href="/en/cli-reference/files">
    The same actions from the terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.