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

# Entities

> Establish identity semantics over encoded traffic.

New tenants start with bundled system entity definitions. Today those defaults
are:

* `ip-user-agent`
* `bot-crawlers`

## List entities

```bash theme={null}
esper entity list
```

## Create entity

```bash theme={null}
esper entity create \
  --name "Login Actor" \
  --description "Track login actors by IP and user agent." \
  --key-field client_ip \
  --key-field user_agent \
  --action login-action
```

This writes `~/.esper/data/entities/login-actor.json` and submits the
entity. `--action` accepts either a UUID or a local action data name.

Available bundled templates:

* `default` - resolves to `ip-user-agent`
* `ip-user-agent` - groups traffic by `client_ip + user_agent`
* `bot-crawlers` - groups common AI and social crawlers by `user_agent` with `contains` matches for known provider tokens

## Update entity

```bash theme={null}
esper entity update --file ./entity-updated.json
```

## Delete entity

```bash theme={null}
esper entity delete <entity-id>
```