> ## 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](/developers/app-code/local-development/bring-your-own-agent), the cloud environment that holds the app's code. 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`](/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](/developers/references/cli/commands/introduction#select-a-target-app). |
| `--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](/developers/references/cli/commands/introduction#json-output).                    |

## Output

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

```
{
  "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

* [Bring your own agent](/developers/app-code/local-development/bring-your-own-agent): How the sandbox works, and what you can change in it
* [`sandbox ls`](/developers/references/cli/commands/sandbox-ls): List directory entries in the sandbox
* [`sandbox grep`](/developers/references/cli/commands/sandbox-grep): Search files in the sandbox for a pattern
* [`sandbox edit`](/developers/references/cli/commands/sandbox-edit): Apply exact string replacements to a file