# write

> Replace the whole content of a file

*Changes something.*

Replace the whole content of a file.

Expects revision, the file's observed content revision. A file's revision is its place
in content history and turns only when its bytes change, so a rename or a move by
someone else does not invalidate a write you prepared. content carries the bytes as text
and content_base64 carries bytes that are not text; exactly one of the two, and at most
1048576 bytes once decoded. On revision_conflict nothing was written: read the item
again, work out what the change means against what is there now, and run it again with
the newly observed revision. Never fetch a fresh revision merely to push a stale change
through.

Read a revision from the stat tool, a listing, a search, the status tool, or any
change's own result. The replaced content is retained as a version, which history lists.

This change takes a key you choose, fresh for this change. If its result never reaches
you, call again with the same key and the same arguments, or ask the status tool with
that key: the same key and the same input is one change, made once.

## Arguments

| Argument | Type | Required | Meaning |
| --- | --- | --- | --- |
| `file_id` | text | yes | The file to replace |
| `content` | bytes | no | The bytes, as text; exactly one of content and content_base64 |
| `content_base64` | bytes | no | The bytes, base64-encoded, for content that is not text |
| `revision` | text | yes | The content revision this change expects to find |
| `key` | text | yes | A key you choose for this change, fresh each time; repeat it to settle a lost result |

## On the command line

```sh
flie agent write FILE_ID --from PATH --revision REV [--key OPERATION_KEY]
```

```sh
flie --json agent write FILE_ID --from ./note.md --revision REV  # replace the whole content
```
