# read

> A file's bytes, current or from a named past content version

*Reads only.*

A file's bytes, current or from a named past content version.

Expects nothing and changes nothing. It answers the file's own revision and version
beside the bytes, so a read is one of the places the revision a later write expects is
read from. A past content version is read instead of the current bytes by naming that
version; there is no restore-version command, so putting earlier content back is this
read followed by a write of those bytes.

As a tool call the bytes come back in the result, bounded, because a result is read by a
model rather than streamed: offset starts the window and limit sizes it, 65536 bytes by
default and 1048576 at most, and next_offset says where the following window begins, or
null when that was the end of the file. Text comes back as a text block, cut back to the
last whole character so a window never returns a mangled one; anything else comes back
as an embedded resource carrying those bytes. Before either comes a text block of JSON
carrying size, sha256, offset, length, next_offset and the file's own revision and
version. Paging a file is offset until next_offset is null.

## Arguments

| Argument | Type | Required | Meaning |
| --- | --- | --- | --- |
| `file_id` | text | yes | The file to read |
| `version` | text | no | A past content version, instead of the current bytes |
| `offset` | count | no | Where this window starts, in bytes from the beginning |
| `limit` | count | no | How many bytes this window may hold; 65536 by default, 1048576 at most |

## On the command line

```sh
flie agent read FILE_ID [--version VERSION_ID] [--to PATH]
```

```sh
flie agent read FILE_ID                                 # raw bytes on stdout
flie agent read FILE_ID --to ./local.md                 # to a new local file; never overwrites
```
