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

> Create or overwrite a file in an app's remote sandbox

Create a new file in an app's [sandbox](/developers/app-code/local-development/bring-your-own-agent), the cloud environment that holds the app's code. The change is committed as part of this command, becomes visible in the Base44 app editor, and is included when you publish, with no separate deploy or push step.

Prefer [`sandbox edit`](/developers/references/cli/commands/sandbox-edit) for changing a file that already exists. It applies surgical replacements and returns a diff, so you can't accidentally discard the rest of the file.

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.

<Note>
  This command needs the `sandbox:write` permission. 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 the proper permissions.
</Note>

## Usage

```bash theme={null}
base44 sandbox write <path>
```

## Arguments

| Argument | Description                         | Required |
| -------- | ----------------------------------- | -------- |
| `<path>` | File path relative to the app root. | 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). |
| `--content <content>` | The file content. If omitted, the content is read from stdin. A single file can be at most 6 MB, rejected with `FILE_TOO_LARGE` past that.                                    |
| `--overwrite`         | Overwrite the file if it already exists. Without it, writing to a path that already exists fails with `OVERWRITE_NOT_ALLOWED`.                                                |
| `--json`              | Keep stdout to just the JSON result, without the interactive status line. See [JSON output](/developers/references/cli/commands/introduction#json-output).                    |

<Note>
  Content piped on stdin is sent exactly as given, including leading and trailing whitespace and the final newline.
</Note>

<Warning>
  You can't use this command to blank out or delete an existing file, since empty content is rejected. To delete a file, run [`base44 sandbox run "rm <path>"`](/developers/references/cli/commands/sandbox-run). To blank one out instead, run `base44 sandbox run "truncate -s 0 <path>"`. To create a new empty file, run `base44 sandbox run "touch <path>"`.
</Warning>

## Output

The command returns JSON:

```
{
  "path": "src/components/Hello.jsx",
  "bytesWritten": 128,
  "created": true,
  "overwritten": false
}
```

| Field          | Description                                         |
| -------------- | --------------------------------------------------- |
| `path`         | Path of the written file, relative to the app root. |
| `bytesWritten` | Number of bytes written.                            |
| `created`      | `true` when the file did not exist before.          |
| `overwritten`  | `true` when an existing file was replaced.          |

## 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 edit`](/developers/references/cli/commands/sandbox-edit): Apply exact string replacements to an existing file
* [`sandbox run`](/developers/references/cli/commands/sandbox-run): Run a shell command in the sandbox
* [`sandbox checkpoint`](/developers/references/cli/commands/sandbox-checkpoint): Save a restore point before or after a set of changes