---
layout: docs
page_title: events - Command
description: |-
  The "events" command interacts with the Vault events subsystem.
---

# events

Use the `events` command to get a real-time display of
[events](/vault/docs/concepts/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

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

`events subscribe` supports the following flags in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.

### Options

- `-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](/boundary/docs/concepts/filtering) 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:
      ```
      data_path == secret/data/foo and operation != write
      ```


### Enterprise options

<EnterpriseAlert product="vault" />

- `-namespaces` `(string)` - Additional **child** namespaces for the
  subscription. Repeat the flag to add additional namespace patterns to the
  subscription request. Vault automatically prepends the issuing namespace for
  the request to the provided namespace. For example, if you include
  `-namespaces=ns2` on a request made in the `ns1` namespace, Vault will attempt
  to subscribe you to events under the `ns1/ns2` and `ns1` namespaces. You can
  use the `*` character to include wildcards in the namespace pattern. By
  default, Vault will only subscribe to events in the requesting namespace.

<Note>
  To subscribe to events across multiple namespaces, you must provide a root
  token or a token associated with appropriate policies across all the targeted
  namespaces. Refer to
  the <a href="/vault/tutorials/enterprise/namespaces">Secure multi-tenancy with
  namespaces</a>tutorial for configuring your Vault instance appropriately.
</Note>