# events

Use the `events` command to get a real-time display of events generated by Vault and subscribe to Vault events. Note that the `events subscribe` runs indefinitly and will not exit on its own unless it encounters an unexpected error. Similar to `tail -f` in the Unix world, you must terminate the process from the command line to end the `events` command.

Specify the desired event types (also called "topics") as a glob pattern. To match against multiple events, use `*` as a wildcard. The command returns serialized JSON objects in the default protobuf JSON serialization format with one line per event received.

### Examples <a href="#examples" id="examples"></a>

Subscribe to all events:

```shell-session
$ vault events subscribe '*'
```

Subscribe to all KV events:

```shell-session
$ vault events subscribe 'kv*'
```

Subscribe to all `kv-v2/data-write` events:

```shell-session
$ vault events subscribe kv-v2/data-write
```

Subscribe to all KV events in the current and `ns1` namespaces for the secret `secret/data/foo` that do not involve writing data:

```shell-session
$ vault events subscribe -namespaces=ns1 -filter='data_path == secret/data/foo and operation != "data-write"' 'kv*'
```

### Usage <a href="#usage" id="usage"></a>

`events subscribe` supports the following flags in addition to the standard set of flags included on all commands.

#### Options <a href="#options" id="options"></a>

* `-timeout`: `(duration: "")` - close the WebSocket automatically after the specified duration.
* `-filter` `(string: "")` - Filter expression used to select events to be sent through the WebSocket.

Refer to the Filter expressions guide in the Boundary documentation for a complete list of filtering options and an explanation on how we evaluate filter expressions.

The following values are available in the filter expression:

* `event_type`: the event type, e.g., `kv-v2/data-write`.

  * `operation`: the operation name that caused the event, e.g., `write`.
  * `source_plugin_mount`: the mount of the plugin that produced the event, e.g., `secret/`
  * `data_path`: the API path that can be used to access the data of the secret related to the event, e.g., `secret/data/foo`
  * `namespace`: the path of the namespace that created the event, e.g., `ns1/`

  The filter string is empty by default. Unfiltered subscription requests match to all events that the requestor has access to for the target event type. When the filter string is not empty, Vault applies the filter conditions after the policy checks to narrow the events provided in the response.

  Filters can be straightforward path matches like `data_path == secret/data/foo`, which specifies that Vault should pass return events that refer to the `secret/data/foo` secret to the WebSocket. Or more complex statements that exclude specific operations. For example:

  ```mdx-code-blocks_codeBlockMargin__TI7B4
  data_path == secret/data/foo and operation != write
  ```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enclaive.cloud/vault/cli/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.