# Following events with keenauth events tail

`keenauth events tail` reads the event API of your environment and prints each customer event as it appears, for example `user.created`. The events are the same as the webhook deliveries: the same envelope and the same `id`. Use it to watch what your integration will receive, or to check that an action produced the event you expect. Press Ctrl-C to stop; the command then exits with code 0.

The command needs the `events:read` permission. It works with an API key and with a `keenauth login` session.

## Usage

```sh
keenauth events tail --types user.created,user.updated
```

| Flag | Description |
|---|---|
| `--types` | Only these event types, comma separated or repeated. |
| `--org` | Only events of this organization (`org_…`). |
| `--payload` | `thin` (default) or `full`. `full` includes the resource and also needs the `users:read` permission. |
| `--after` | Where to start: `latest` (default) prints only events that happen from now on; a cursor printed by an earlier run continues from there. |
| `--interval` | Time between two checks when there are no new events, from `1s` to `60s`. Default: `5s`. |
| `--output`, `-o` | `table`, `json` or `yaml`. Without the flag the CLI prints a table on a terminal and JSON otherwise. |

An invalid filter, cursor or interval stops the command with code 2 before any request is sent.

## Output

- `table`: one line per event with the time, type, sequence number and event ID.
- `json`: each event exactly as the server sent it, one JSON object per line (newline-delimited JSON). This is the default when stdout is not a terminal.
- `yaml`: one YAML document per event, each starting with `---`.

Events are printed in the environment's event order (`seq`). When you stop the command, it prints the cursor to continue from on stderr:

```text
to continue from here: --after <cursor>
```

Run `keenauth events tail --after <cursor>` later to print the events you missed in between. Events are kept for 30 days.

## How it follows

The command asks for the events after its cursor, prints them and moves the cursor to the one the response returns. When the response says more events are waiting, it asks again at once; otherwise it waits `--interval` and asks again.

## Exit codes

| Code | Meaning |
|---|---|
| `0` | Stopped with Ctrl-C. |
| `1` | A server error or a network failure, for example a cursor of another environment. |
| `2` | Usage error: an invalid filter, cursor, interval or output format. No request was sent. |
| `3` | The credential is missing, or the server answered `401` or `403`. |
| `4` | The plan does not include the feature (`403` with `plan_feature_unavailable`). |