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

# Command Records

> Command records are stream records S2 interprets as service-side directives.

Command records signal operations that are interpreted by the service.

S2 [SDKs](/sdk) and the [CLI](/cli) make it easy to create supported command records, so most applications do not need to construct them directly.

Concretely, a command record is a record with:

1. A single header with an empty name. Empty header names are not allowed in any other context.
2. The operation encoded in that header value.
3. The command payload in the record body.

<Note>
  Command records take up a sequence number on the stream, and will be returned to reads. It is easy to test and filter out commands if needed, with the logic `len(headers) == 1 && headers[0].name == b""`.
</Note>

## Operations

Operations that are currently supported:

* [`fence`](/concepts/concurrency-control#fencing-tokens) — set a fencing token for cooperative write exclusion. Payload is up to 36 UTF-8 bytes; an empty payload clears the token.
* [`trim`](/concepts/trimming#trim-point) — set a trim point to remove older records. Payload is exactly 8 big-endian bytes representing the desired earliest sequence number.

<Accordion title="Constructing command records via REST">
  <Tabs>
    <Tab title="fence">
      ```bash theme={null}
      curl -X POST "https://{basin}.b.s2.dev/v1/streams/my-stream/records" \
          -H "Authorization: Bearer <token>" \
          -H "s2-format: raw" \
          -H "Content-Type: application/json" \
          -d '{
            "records": [
              {
                "headers": [
                  ["", "fence"]
                ],
                "body": "producer-123"
              }
            ]
          }'
      ```
    </Tab>

    <Tab title="trim">
      ```bash theme={null}
      curl -X POST "https://{basin}.b.s2.dev/v1/streams/my-stream/records" \
          -H "Authorization: Bearer <token>" \
          -H "s2-format: base64" \
          -H "Content-Type: application/json" \
          -d '{
            "records": [
              {
                "headers": [
                  ["", "dHJpbQ=="]
                ],
                "body": "AAAAAAAAAGQ="
              }
            ]
          }'
      ```
    </Tab>
  </Tabs>
</Accordion>

## See also

<CardGroup cols={3}>
  <Card title="Concurrency control" icon="sliders" href="/concepts/concurrency-control">
    Coordinate writers with match sequence numbers and fencing tokens.
  </Card>

  <Card title="Trimming" icon="scissors" href="/concepts/trimming">
    Discard older records by setting a stream trim point.
  </Card>

  <Card title="Appends" icon="pen" href="/concepts/appends">
    Understand append acknowledgements, batching, and durability.
  </Card>
</CardGroup>