# Manage the dead letter queue with the CLI

> List, replay, and discard dead letter queue events from the command line using the Unity Gaming Services CLI.

You can use the [Unity Gaming Services CLI](https://services.docs.unity.com/guides/ugs-cli/latest/general/overview) to interact with the dead letter queue (DLQ). The CLI allows you to list dead letter queue (DLQ) events, fetch a single event by ID, replay events to retry delivery, and discard events from the command line.

## Prerequisites

For detailed CLI setup instructions, refer to the [Unity Gaming Services CLI Get Started guide](https://services.docs.unity.com/guides/ugs-cli/latest/general/get-started/install-the-cli/).

To follow this guide, you first need to complete the following actions:

1. [Install the UGS CLI](https://services.docs.unity.com/guides/ugs-cli/latest/general/get-started/install-the-cli/).

2. Configure your Project ID and Environment in the following format:
   `ugs config set project-id <your-project-id>`
   `ugs config set environment-name <your-environment-name>`

3. Configure a Service Account with the required roles for [Triggers](https://services.docs.unity.com/docs/service-account-auth/index.html#triggers-configuration-editor):
   * **Triggers DLQ Viewer** (to list and get events).
   * **Triggers DLQ Manager** (to also replay and discard).

Refer to [Get Authenticated](https://services.docs.unity.com/guides/ugs-cli/latest/general/get-started/get-authenticated/).

## Using the CLI

For a full reference of all commands and options, refer to the [Triggers Command Line documentation](https://services.docs.unity.com/guides/ugs-cli/latest/triggers/Triggers%20Command%20Line/overview).

For examples that use `<event-id>`, replace `<event-id>` with the event ID from the list output.

> **Note:**
>
> The `ugs triggers dlq` command is also available as `ugs tr dlq`.

### List DLQ events

List events in the dead letter queue for the current project and environment:

```bash
ugs triggers dlq list
```

You can optionally filter by status or limit the number of results:

```bash
ugs triggers dlq list --status pending
ugs triggers dlq list --limit 50
```

The output shows event ID, trigger name, source, status, and time created for each event.

### Get a DLQ event

Fetch a single DLQ event by ID and view its payload and metadata:

```bash
ugs triggers dlq get <event-id>
```

### Replay DLQ events

Replay queues the event for retry. The CLI returns immediately; a background worker re-publishes the event asynchronously.

Replay a single pending event:

```bash
ugs triggers dlq replay <event-id>
```

Replay all pending events in the project and environment:

```bash
ugs triggers dlq replay --all
```

### Discard DLQ events

Discard a single pending event (remove it from the queue without reprocessing):

```bash
ugs triggers dlq discard <event-id>
```

Discard all pending events in the project and environment:

```bash
ugs triggers dlq discard --all
```

> **Warning:**
>
> Discarding all events is a destructive operation. Only events in a discardable state (for example Pending) are removed. You can run `ugs triggers dlq list --status pending` first to see which triggers you can remove.

## Additional resources

* [Dead letter queue](/triggers/tutorials/manage-dlq/dead-letter-queue.md)
* [Failure handling](/triggers/failure-handling.md)
* [Limits](/triggers/limits.md#dead-letter-queue)
* [Manage the dead letter queue in the Unity Dashboard](./unity-dashboard)
* [Manage the dead letter queue with the REST API](./rest-api)