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

> Search files for a pattern in an app's remote sandbox

Search the files in an app's [sandbox](/developers/app-code/local-development/bring-your-own-agent) for a pattern and get back the matching lines with their file paths and line numbers. Use it to locate the code you want to change before reading or editing it. If the result comes back with `truncated` set to `true`, it's incomplete: raise `--max-results` or narrow the search with `--path` and `--glob` to get a complete result.

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 grep <pattern>
```

## Arguments

| Argument    | Description                                                            | Required |
| ----------- | ---------------------------------------------------------------------- | -------- |
| `<pattern>` | The pattern to search for. Treated as a regular expression by default. | 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). |
| `--path <path>`     | Subtree to search, relative to the app root. Defaults to the whole app.                                                                                                       |
| `--no-regex`        | Treat the pattern as a literal string instead of a regular expression.                                                                                                        |
| `--case-sensitive`  | Match case. The search is case-insensitive by default.                                                                                                                        |
| `--glob <glob>`     | Only search files matching this glob, for example `"*.tsx"`.                                                                                                                  |
| `--max-results <n>` | Maximum number of matching lines to return. Defaults to `200`, maximum `1000`.                                                                                                |
| `--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:

```
{
  "matches": [
    { "path": "src/pages/Home.jsx", "line": 42, "text": "  const [items, setItems] = useState([]);" }
  ],
  "truncated": false,
  "returnedMatches": 1
}
```

Each match in `matches` has:

| Field  | Description                                                                                    |
| ------ | ---------------------------------------------------------------------------------------------- |
| `path` | File containing the match. Can be `null` for a match the search could not attribute to a file. |
| `line` | Line number of the match. Can be `null`.                                                       |
| `text` | The matched line's text.                                                                       |

The response itself also carries:

| Field             | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| `truncated`       | `true` when more matches existed than `--max-results` allowed. |
| `returnedMatches` | Number of matches in `matches`.                                |

## Example

Find every use of a hook in the `src` tree, in `.tsx` files only:

```bash theme={null}
base44 sandbox grep useEffect --path src --glob "*.tsx" --max-results 500
```

## 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 read`](/developers/references/cli/commands/sandbox-read): Read file contents from the sandbox
* [`sandbox ls`](/developers/references/cli/commands/sandbox-ls): List directory entries in the sandbox
* [`sandbox edit`](/developers/references/cli/commands/sandbox-edit): Apply exact string replacements to a file