> ## 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](https://docs.base44.com/developers/app-code/sandbox/overview.md). 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`](https://docs.base44.com/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`](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.

> [!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`](https://docs.base44.com/developers/references/cli/commands/login) again to start a session that has the proper permissions.

## 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](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`. |
| `--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](https://docs.base44.com/developers/references/cli/commands/introduction.md#json-output). |

> [!NOTE]
>
> Content piped on stdin is sent exactly as given, including leading and trailing whitespace and the final newline.

> [!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>"`](https://docs.base44.com/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>"`.

## Output

The command returns JSON:

```json theme={null}
{
  "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

* [Cloud sandbox](https://docs.base44.com/developers/app-code/sandbox/overview.md): How the sandbox works, and what you can change in it
* [`sandbox edit`](https://docs.base44.com/developers/references/cli/commands/sandbox-edit): Apply exact string replacements to an existing file
* [`sandbox run`](https://docs.base44.com/developers/references/cli/commands/sandbox-run): Run a shell command in the sandbox
* [`sandbox checkpoint`](https://docs.base44.com/developers/references/cli/commands/sandbox-checkpoint): Save a restore point before or after a set of changes


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