---
title: "policies create"
description: "Create a policy profile"
canonical: "https://pgbeam.com/docs/cli/policies/create"
last-updated: "2026-10-30T10:36:50.000Z"
---

# policies create

> Create a policy profile

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

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

Create a policy profile. Provide a name and access mode, then author the rules with flags (`--allow`, `--deny`, `--mask`, budget flags, and the write-safety flags `--write-mode`, `--approval-mode`, `--approval-timeout-seconds`, `--approval-auto-max-rows`, `--migration-safety`, plus `--query-mode` to admit only the project's query templates) or pass a JSON file describing the full profile (statement rules, allow/deny lists, masking, budgets). Fields set via `--file` are overlaid by any individual flags. The resolved profile is validated against the API schema before anything is sent; `--dry-run` prints the resolved profile JSON without calling the API.

## Usage

```bash
pgbeam policies create [flags]
```

## Options

| Option                               | Description                                                                                                             | Required | Default |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
| `--name <value>`                     | Policy profile name                                                                                                     | Yes      | -       |
| `--mode <value>`                     | Access mode: read_only or read_write                                                                                    | No       | -       |
| `--write-mode <value>`               | How writes are handled: normal or rollback                                                                              | No       | -       |
| `--approval-mode <value>`            | Which statements need approval: off, writes, ddl, or all                                                                | No       | -       |
| `--approval-timeout-seconds <value>` | How long a held statement waits for a decision before expiring                                                          | No       | -       |
| `--approval-auto-max-rows <value>`   | Statements touching at most this many rows are auto-approved (0 disables)                                               | No       | -       |
| `--migration-safety <value>`         | Migration safety mode: off, warn, or block                                                                              | No       | -       |
| `--query-mode <value>`               | What an agent may send: sql (any statement the policy allows) or templates (only the project's enabled query templates) | No       | -       |
| `--table-allowlist <value>`          | Comma-separated relations to allow                                                                                      | No       | -       |
| `--table-denylist <value>`           | Comma-separated relations to deny                                                                                       | No       | -       |
| `--allow <value>`                    | Relation to allowlist (repeatable, or comma-separated)                                                                  | No       | -       |
| `--deny <value>`                     | Relation to denylist (repeatable, or comma-separated)                                                                   | No       | -       |
| `--mask <value>`                     | Masking rule as table.column=kind, where kind is redact, null, hash, last4, or email_domain (repeatable)                | No       | -       |
| `--max-rows <value>`                 | Max rows returned per query (0 means unlimited)                                                                         | No       | -       |
| `--max-affected-rows <value>`        | Hard cap on rows a single write may affect; over-cap writes are rolled back and blocked (0 means unlimited)             | No       | -       |
| `--budget-queries-per-hour <value>`  | Max queries per rolling hour (0 means unlimited)                                                                        | No       | -       |
| `--budget-queries-per-day <value>`   | Max queries per day (0 means unlimited)                                                                                 | No       | -       |
| `--egress-bytes-per-day <value>`     | Per-day egress budget in bytes (0 means unlimited)                                                                      | No       | -       |
| `--statement-timeout-ms <value>`     | Upstream statement timeout for agent sessions (0 uses the project default)                                              | No       | -       |
| `--file <value>`                     | Path to a JSON file with the full profile body                                                                          | No       | -       |
| `--dry-run`                          | Print the resolved profile JSON that would be sent, without calling the API                                             | No       | `false` |

> **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
# Create a read-only profile
pgbeam policies create --name "read-only" --mode read_only

# Allowlist two tables and mask a column
pgbeam policies create --name support --allow public.users --allow public.orders --mask users.email=redact

# Cap budgets and rows
pgbeam policies create --name bots --budget-queries-per-day 5000 --max-rows 1000 --statement-timeout-ms 3000

# Read-write profile with rollback writes and approval for DDL
pgbeam policies create --name deploys --mode read_write --write-mode rollback --approval-mode ddl --migration-safety warn

# Preview the resolved profile without creating it
pgbeam policies create --name analytics --file ./policy.json --dry-run
```

## Output

Prints the created policy profile. With --dry-run, prints the resolved profile JSON that would be sent and exits without calling the API.