---
title: "policies replay"
description: "Replay recorded agent traffic against a policy"
canonical: "https://pgbeam.com/docs/cli/policies/replay"
last-updated: "2026-10-20T17:41:58.000Z"
---

# policies replay

> Replay recorded agent traffic against a policy

URL: https://pgbeam.com/docs/cli/policies/replay

{/* Auto-generated from CLI commands. Do not edit. Run `pnpm generate:cli-docs` to regenerate. */}

Replay the project's recorded agent audit traffic against a candidate policy and print what would change: which queries that ran would now be blocked, which blocked queries would now be permitted, and which results would be masked or row-filtered. Supply exactly one of `--policy` (an existing saved policy ID) or `--draft` (a JSON file describing an unsaved draft policy). Traffic is deduplicated by normalized query shape, newest first, and every statement is evaluated through the data plane's own policy engine, so verdicts match real enforcement. The replay reads only the audit log; it never connects to the upstream database. By default it covers every credential in the project, including credentials bound to other policies, whose behaviour saving this candidate cannot change; pass `--bound-policy` to narrow it to the credentials a policy actually governs, which is usually the question you want answered before editing a live policy.

## Usage

```bash
pgbeam policies replay [flags]
```

## Options

| Option                   | Description                                                                                                        | Required | Default |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------ | -------- | ------- |
| `--policy <value>`       | ID of an existing saved policy to replay against                                                                   | No       | -       |
| `--draft <value>`        | Path to a JSON file with a draft policy body to replay against                                                     | No       | -       |
| `--credential <value>`   | Restrict the replay to traffic recorded for one agent credential                                                   | No       | -       |
| `--bound-policy <value>` | Restrict the replay to traffic from the credentials bound to this policy ID (mutually exclusive with --credential) | No       | -       |
| `--start <value>`        | Start of the traffic window (RFC3339; default 7 days before the end)                                               | No       | -       |
| `--end <value>`          | End of the traffic window (RFC3339; default now)                                                                   | No       | -       |
| `--limit <value>`        | Maximum distinct queries to replay, newest first (1-500; default 200)                                              | No       | -       |

> **Global options**
>
> All [global options](/docs/cli/global-options) (`--token`, `--profile`,
> `--project`, `--org`, `--json`, `--no-color`, `--no-trunc`, `--debug`) are
> also available on this command.

## Examples

```bash
# Replay the last 7 days of traffic against a saved policy
pgbeam policies replay --policy pol_xxx

# Replay only the traffic the policy governs, before editing it
pgbeam policies replay --draft ./policy.json --bound-policy pol_xxx

# Replay one credential's traffic against a draft policy
pgbeam policies replay --draft ./policy.json --credential cred_xxx

# Replay a custom window and get the full result as JSON
pgbeam policies replay --policy pol_xxx --start 2026-07-01T00:00:00Z --end 2026-07-08T00:00:00Z --json
```

## Output

Prints a summary (queries replayed, would-block/mask/row-filter counts, newly blocked and newly allowed changes) followed by the changed queries. With --json, returns the full result object including every per-query decision.