> ## Documentation Index
> Fetch the complete documentation index at: https://s2.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Read

> Read stream records from a sequence number, timestamp, or tail offset with the S2 CLI.

Read records from a stream.

### Read from the beginning

```bash theme={null}
s2 read s2://my-basin/my-stream -s 0 -n 10
```

```
⦿ 54 bytes (3 records in range 0..=2)
hello world
foo bar
third record
```

### JSON output

```bash theme={null}
s2 read s2://my-basin/my-stream -s 0 -n 3 --format json
```

```json theme={null}
{"seq_num":0,"timestamp":1771390606217,"body":"hello world"}
{"seq_num":1,"timestamp":1771390606217,"body":"foo bar"}
{"seq_num":2,"timestamp":1771390606217,"body":"third record"}
```

### Read from a timestamp

```bash theme={null}
# Absolute (milliseconds since epoch)
s2 read s2://my-basin/my-stream --timestamp 1771390606217

# Relative
s2 read s2://my-basin/my-stream --ago 1h
```

### Read from a tail offset

```bash theme={null}
s2 read s2://my-basin/my-stream --tail-offset 100
```

### Follow for new records

Without a limit (`-n` or `-b`), `read` keeps tailing and waits for new records indefinitely:

```bash theme={null}
s2 read s2://my-basin/my-stream -s 0
```

### Encrypted streams

```bash theme={null}
export S2_ENCRYPTION_KEY="$(cat ./stream-key.b64)"

s2 read s2://my-basin/my-stream -s 0 -n 10
```

Or pass the key on the command line:

```bash theme={null}
s2 read s2://my-basin/my-stream \
  --encryption-key-file ./stream-key.b64 \
  -s 0 -n 10
```

<Note>
  The same `--encryption-key` and `--encryption-key-file` flags also apply to `s2 tail`.
</Note>

### Options

| Flag                    | Description                                                                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-s, --seq-num`         | Starting sequence number (inclusive).                                                                                                                                                |
| `--timestamp`           | Starting timestamp in milliseconds since Unix epoch (inclusive).                                                                                                                     |
| `--ago`                 | Starting timestamp as a human-friendly delta from current time e.g. "1h", which will be converted to milliseconds since Unix epoch.                                                  |
| `--tail-offset`         | Start from N records before the tail of the stream.                                                                                                                                  |
| `-n, --count`           | Limit the number of records returned.                                                                                                                                                |
| `-b, --bytes`           | Limit the number of bytes returned.                                                                                                                                                  |
| `--until`               | Exclusive end-timestamp in milliseconds since Unix epoch. If provided, results will be limited such that all records returned will have a timestamp \< the one provided via `until`. |
| `--clamp`               | Clamp the start position at the tail position.                                                                                                                                       |
| `--format`              | Output format.                                                                                                                                                                       |
| `-o, --output`          | Output records to a file or stdout. Use `-` to write to stdout.                                                                                                                      |
| `-k, --encryption-key`  | Base64-encoded encryption key material. Alternatively, set `S2_ENCRYPTION_KEY`.                                                                                                      |
| `--encryption-key-file` | Read base64-encoded encryption key material from file.                                                                                                                               |

***

## Tail

Like `tail` on Unix, it shows the last N records from a stream.

```bash theme={null}
s2 tail s2://my-basin/my-stream -n 5
```

Follow for new records with `-f`:

```bash theme={null}
s2 tail s2://my-basin/my-stream -f
```