> ## 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 ls

> List directory entries in an app's remote sandbox

List the files and directories inside an app's [sandbox](https://docs.base44.com/developers/app-code/sandbox/overview.md). This reads the remote sandbox, not your local files.

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 ls [path]
```

## Arguments

| Argument | Description | Required |
| - | - | - |
| `path` | Directory to list, relative to the app root. Defaults to the app root. | No |

## 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`. |
| `--recursive` | List nested entries. |
| `--max-depth <n>` | Maximum depth to descend when `--recursive` is set, between `1` and `10`. Defaults to `3`. |
| `--include-hidden` | Include dotfiles. |
| `--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:

```json theme={null}
{
  "entries": [
    { "name": "pages", "path": "src/pages", "type": "directory" },
    { "name": "Home.jsx", "path": "src/pages/Home.jsx", "type": "file", "size": 1284 }
  ],
  "truncated": false
}
```

Each entry in `entries` has:

| Field | Description |
| - | - |
| `name` | The entry's own name, the last segment of its path. |
| `path` | The entry's full path, relative to the app root. Matches `name` only for a top-level, non-recursive listing; a nested entry's `path` carries the directory prefix that `name` leaves out. |
| `type` | Either `file` or `directory`. |
| `size` | Size in bytes. Present on files only. |

The response itself also carries:

| Field | Description |
| - | - |
| `truncated` | `true` when the listing hit the limit of 1000 entries and was cut short. |

## Example

List the `src` directory two levels deep:

```bash theme={null}
base44 sandbox ls src --recursive --max-depth 2
```

## 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 read`](https://docs.base44.com/developers/references/cli/commands/sandbox-read): Read file contents from the sandbox
* [`sandbox grep`](https://docs.base44.com/developers/references/cli/commands/sandbox-grep): Search files in the sandbox for a pattern
* [`sandbox run`](https://docs.base44.com/developers/references/cli/commands/sandbox-run): Run a shell command in the sandbox


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