> ## 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 edit
> Apply exact string replacements to a file in an app's remote sandbox
Change an existing file in an app's [sandbox](/developers/app-code/local-development/bring-your-own-agent) by replacing exact strings. You describe each replacement as an old string and a new string, and the command returns a unified diff of what changed. Pass `--dry-run` to see the diff without writing anything.
This is safer than overwriting the whole file with [`sandbox write`](/developers/references/cli/commands/sandbox-write), because you only touch the text you named and you get a reviewable diff back.
Your change is committed as part of this command, becomes visible in the Base44 app editor, and is included when you publish. There is no separate deploy or push step.
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.
This command needs the `sandbox:write` permission, including for `--dry-run`. The CLI requests it when you sign in, and an existing session cannot gain it afterwards. If the command fails with an authorization error, run [`base44 login`](/developers/references/cli/commands/login) again to start a session that has it.
## Usage
```bash theme={null}
base44 sandbox edit
```
## Arguments
| Argument | Description | Required |
| -------- | ----------------------------------- | -------- |
| `` | File path relative to the app root. | Yes |
## Flags
| Flag | Description |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--app-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). |
| `--edits-json ` | A JSON array of edits. If omitted, the array is read from stdin. |
| `--dry-run` | Return the unified diff without writing the file. |
| `--json` | Keep stdout to just the JSON result, without the interactive status line. See [JSON output](/developers/references/cli/commands/introduction#json-output). |
## Edit format
`--edits-json` takes a JSON array of one or more edit objects:
```json theme={null}
[{ "old_text": "Welcome", "new_text": "Welcome back", "replace_all": false }]
```
| Property | Description | Required |
| ------------- | -------------------------------------------------------------------------------------------------------------------- | -------- |
| `old_text` | The exact text to replace. Cannot be empty, and must appear exactly once in the file unless `replace_all` is `true`. | Yes |
| `new_text` | The text to put in its place. Can be an empty string, which deletes the matched text. | Yes |
| `replace_all` | Replace every occurrence of `old_text` instead of requiring a single match. Defaults to `false`. | No |
One command can carry up to 100 edits. They apply in order, each one matching against the file as the previous edits left it rather than the original, but the batch is all-or-nothing. If any single edit fails, none of them are written. The file being edited, and the file the edits would produce, can be at most 6 MB. A larger file is rejected with `FILE_TOO_LARGE`.
An edit fails with `EDIT_TEXT_NOT_FOUND` when `old_text` is not present in the file, or with `EDIT_TEXT_NOT_UNIQUE` when it matches more than once and `replace_all` is not set. Include more surrounding context in `old_text` to make it unique, or set `replace_all`. An edit that would leave the file empty fails with `EMPTY_EDIT_RESULT`, so to delete a file use [`base44 sandbox run "rm "`](/developers/references/cli/commands/sandbox-run).
## Output
The command returns JSON:
```
{
"path": "src/pages/Home.jsx",
"diff": "--- a/src/pages/Home.jsx\n+++ b/src/pages/Home.jsx\n@@ -12,7 +12,7 @@\n- Welcome
\n+ Welcome back
\n",
"applied": true
}
```
| Field | Description |
| --------- | -------------------------------------------------------------------- |
| `path` | Path of the edited file, relative to the app root. |
| `diff` | Unified diff of the change. |
| `applied` | `true` when the file was written, `false` for a `--dry-run` preview. |
## Example
Preview a change before making it:
```bash theme={null}
base44 sandbox edit src/pages/Home.jsx --dry-run --edits-json '[{"old_text":"Welcome","new_text":"Welcome back"}]'
```
## 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 write`](/developers/references/cli/commands/sandbox-write): Create a new file in the sandbox
* [`sandbox read`](/developers/references/cli/commands/sandbox-read): Read a file before editing it
* [`sandbox checkpoint`](/developers/references/cli/commands/sandbox-checkpoint): Save a restore point before or after a set of changes