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

# sandbox read

> Read file contents from an app's remote sandbox

Read one or more files from an app's [sandbox](https://docs.base44.com/developers/app-code/sandbox/overview.md). Use `--offset` and `--limit` to pull a line range instead of a whole file. A file that cannot be read does not fail the command. That file comes back with an `error` object holding a `code` and a `message` instead of `content`, and the other files in the same command still return normally.

Every path is relative to the app root. `sandbox` commands don't require a local project. Target an app by passing [`--app-id`](https://docs.base44.com/developers/references/cli/commands/introduction#select-a-target-app), setting the `BASE44_APP_ID` environment variable, or running the command from a linked project if you have one.

## Usage

```bash theme={null}
base44 sandbox read <paths...>
```

## Arguments

| Argument | Description | Required |
| - | - | - |
| `<paths...>` | One or more file paths relative to the app root, separated by spaces. Up to 50 paths per command. | Yes |

## Flags

| Flag | Description |
| - | - |
| `--app-id <id>` | Target the specified app. Defaults to the app linked in the current project. See [Select a target app](https://docs.base44.com/developers/references/cli/commands/introduction.md#select-a-target-app). |
| `--branch <name>` | [Target a branch](https://docs.base44.com/developers/references/cli/commands/introduction.md#target-a-branch) of the app by exact name. Defaults to `main`. |
| `--offset <n>` | Line to start reading from, counting from `1`. Defaults to the start of the file. |
| `--limit <n>` | Maximum number of lines to return, counting from `--offset`. |
| `--json` | Keep stdout to just the JSON result, without the interactive status line. See [JSON output](https://docs.base44.com/developers/references/cli/commands/introduction.md#json-output). |

## Output

The command returns JSON with one entry per requested path, in the order you passed them:

```json theme={null}
{
  "files": [
    {
      "path": "src/App.jsx",
      "content": "import { useState } from \"react\";\n...",
      "startLine": 1,
      "endLine": 200,
      "totalLines": 412,
      "truncated": false
    }
  ]
}
```

| Field | Description |
| - | - |
| `path` | The requested path, relative to the app root. |
| `content` | The file's content for the requested range. Absent when `error` is present. |
| `startLine` | First line included in `content`. |
| `endLine` | Last line included in `content`. |
| `totalLines` | Total number of lines in the file. Compare it against `endLine` to see how much you did not read. |
| `truncated` | `true` when the content was cut short for exceeding the size cap. A line range you asked for with `--offset` and `--limit` is not truncation, so this stays `false`. |
| `error` | Present instead of `content` when the file could not be read. See below. |

A single file returns at most about 1 MB of content, and one command returns at most 6 MB across all files. Read a line range with `--offset` and `--limit` when a file is larger than that, or split the paths across several commands.

## Errors

A file's `error.code` is one of:

| Code | Meaning |
| - | - |
| `NOT_FOUND` | The file does not exist. |
| `BINARY_FILE` | The file is not valid UTF-8 text. |
| `READ_BUDGET_EXCEEDED` | The file is past the size budget of the request. |
| `PATH_OUTSIDE_SANDBOX` | The path climbs above the app root or is absolute. |
| `PROTECTED_PATH` | The path is off-limits to the file commands. |

## Example

Read the first 200 lines of a page component:

```bash theme={null}
base44 sandbox read src/pages/Home.jsx --offset 1 --limit 200
```

## See also

* [Cloud sandbox](https://docs.base44.com/developers/app-code/sandbox/overview.md): How the sandbox works, and what you can change in it
* [`sandbox ls`](https://docs.base44.com/developers/references/cli/commands/sandbox-ls): List directory entries in the sandbox
* [`sandbox grep`](https://docs.base44.com/developers/references/cli/commands/sandbox-grep): Search files in the sandbox for a pattern
* [`sandbox edit`](https://docs.base44.com/developers/references/cli/commands/sandbox-edit): Apply exact string replacements to a file


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