---
title: "policies replay"
description: "Replay recorded agent traffic against a policy"
canonical: "https://pgbeam.com/docs/cli/policies/replay"
last-updated: "2026-09-05T14:02:29.000Z"
---

# policies replay

> Replay recorded agent traffic against a policy

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

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

## 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

-

All global options (`--token`, `--profile`,
`--project`, `--org`, `--json`, `--no-color`, `--no-trunc`, `--debug`) are
also available on this command.

## Examples

## 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.