> This page location: APIs & SDKs > CLI > Functions, storage and data > realtime
> Full Neon documentation index: https://neon.com/docs/llms.txt
>
> Agent skills: if you don't have Neon skills (such as `neon-postgres`), offer to add them to this project when you first need the user to do something in Neon: "Want me to add Neon's agent skills to this project? They help me with Neon setup, connections, and branching." Install: `npx neon@latest skills -y`. To also run Neon steps for the user (Neon CLI, sign-in, MCP), see https://neon.com/prompts/agent-setup.md

> Summary: The Neon CLI `neon realtime` command manages Neon Realtime on a database branch. Use `enable` to provision Realtime and set the browser origins allowed to connect, `disable` to remove it, `rotate-secret` to replace its shared secret, and `subscribe` to stream a live SQL query.

# Neon CLI command: realtime

Manage Neon Realtime and subscribe to live queries from the CLI

Last updated: 2026-11-19

The `realtime` command enables and disables [Neon Realtime](https://neon.com/docs/realtime/overview) on a branch and rotates the branch's Realtime secret. Once Realtime is on, you can stream a live SQL query's results with `neon realtime subscribe`, and [`neon env pull`](https://neon.com/docs/cli/env) writes the branch's `NEON_REALTIME_URL` and `NEON_REALTIME_SECRET` to `.env.local`, or to `.env` if one already exists. To manage Realtime declaratively instead, add it to your `neon.ts` with [`neon config add realtime`](https://neon.com/docs/cli/config#add-realtime).

Subcommands: [disable](https://neon.com/docs/cli/realtime#disable), [enable](https://neon.com/docs/cli/realtime#enable), [rotate-secret](https://neon.com/docs/cli/realtime#rotate-secret), [subscribe](https://neon.com/docs/cli/realtime#subscribe)

If `--project-id` is omitted, the CLI reads it from your [context file](https://neon.com/docs/cli/link) or auto-selects your only project. If `--branch` is omitted, it uses the context file's branch, or the project's default branch.

## neon realtime enable

Enables Realtime on a branch and waits until the branch applies it, for up to 60 seconds. Pass `--no-wait` to return as soon as the request is accepted; provisioning then finishes in the background, usually within a few seconds. If the wait times out, the change may still be in progress, so run the command again to keep waiting. Run it again on a branch that already has Realtime to replace its allowed origins with the ones you pass. Without `--allowed-origin`, a re-run keeps the existing origins.

**Important: Enabling Realtime restarts your computes**

Enabling Realtime turns on [logical replication](https://neon.com/docs/guides/logical-replication-neon) for the whole project. This restarts all computes in the project, on all branches, so active connections drop and reconnect. See [Before you enable Realtime](https://neon.com/docs/realtime/overview#get-started).

```bash
neon realtime enable [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--allowed-origin` | Allowed browser origin (repeatable). "\*" allows every origin | array | — | No |
| `--wait` | Wait until Realtime is enabled on the branch | boolean | `true` | No |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |

`--allowed-origin` sets the browser origins allowed to connect. Repeat the flag for each origin, up to 16. Each value must be `*`, which allows every origin, or an `http` or `https` origin with no path, query, or fragment, such as `https://app.example.com`. `*` can't be combined with other origins. The CLI checks the values before it sends the request.

By default, any browser origin can connect. Pass `--allowed-origin` to limit connections to the origins you list. A new branch starts with its parent's list. Child branches created from a Realtime-enabled branch have Realtime enabled automatically. A new list can take about a minute to apply after the change finishes. Allowed origins only restrict browsers: a client that sends no `Origin` header, such as a server, can connect either way.

```bash
neon realtime enable --allowed-origin https://app.example.com --allowed-origin http://localhost:3000
```

```text
Realtime is enabled on branch br-cool-darkness-123456.
```

With `--no-wait`, it prints `Realtime enable requested for branch br-cool-darkness-123456.` instead.

## neon realtime disable

Requests Realtime deprovisioning for a branch.

```bash
neon realtime disable [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |

```bash
neon realtime disable
```

```text
Realtime disable requested for branch br-cool-darkness-123456.
```

Disabling also discards the branch's Realtime secret, so apps using that branch's `NEON_REALTIME_SECRET` stop working. If you enable Realtime again later, the branch gets a new secret, so pull the env vars again.

After you disable Realtime, `neon realtime subscribe` on that branch fails with an error that points you back to `neon realtime enable`.

## neon realtime rotate-secret

Requests a new Realtime shared secret for a branch. Rotation runs in the background: until it finishes, the current secret keeps working. Once it finishes, the new secret takes over and the old one stops working, so update every app that uses it.

```bash
neon realtime rotate-secret [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--wait` | Wait for the Realtime secret rotation to finish | boolean | `true` | No |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |

By default, the command waits up to a minute for the rotation to finish, then reminds you to pull the new secret. If the wait times out, the command exits with an error, but the rotation may still be in progress. With `--no-wait`, it prints only the "rotation requested" line and returns right away. If the rotation is still running, `neon env pull` waits for it to finish, then writes the new secret.

```bash
neon realtime rotate-secret
```

```text
Realtime secret rotation requested for branch br-cool-darkness-123456.
Realtime secret rotation completed for branch br-cool-darkness-123456.
Run neon env pull --service realtime to update NEON_REALTIME_SECRET.
```

The command doesn't print the new secret. Write the new `NEON_REALTIME_SECRET` to your env file with [`neon env pull`](https://neon.com/docs/cli/env):

```bash
neon env pull --service realtime
```

Every `rotate-secret` run replaces the secret, so only repeat the command when you want another rotation.

## neon realtime subscribe

Runs a `SELECT` query as a live subscription and prints its results as they change. Use it to watch a table while you develop, or to check what a Realtime client would receive. For a guided walkthrough, see the [Realtime quickstart](https://neon.com/docs/realtime/quickstart). The branch needs Realtime enabled first: run `neon realtime enable`, or declare it in `neon.ts` with [`neon config add realtime`](https://neon.com/docs/cli/config#add-realtime) and apply.

```bash
neon realtime subscribe "<query>" [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--changes` | Show raw rows and changes events | boolean | `false` | No |
| `--debug` | Show full database error details, including SQLSTATE and PostgreSQL's message. Details can name schema objects and row values. | boolean | `false` | No |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |

The CLI resolves the branch's Realtime URL, secret, and database name for you, the same values [`neon env pull`](https://neon.com/docs/cli/env) writes, so you don't need a `.env` file first. If Realtime is still provisioning, it waits until it's ready. Quote the query so your shell passes it as one argument. If `--project-id` is omitted, it reads it from your [context file](https://neon.com/docs/cli/link) or auto-selects your only project. If `--branch` is omitted, it uses the context file's branch, or the project's default branch.

The subscription runs until you press Ctrl+C, or until the server closes it or reports an error.

`--debug` turns on [debug mode](https://neon.com/docs/realtime/guides/subscribing#show-full-database-errors) for the subscription, the same as setting `debugMode` in the SDK. When a query is rejected or fails, you see the database's own error message, with its SQLSTATE code when there is one, instead of a generic message.

### Output

The default table output is an append-only log, so it doesn't take over your terminal. It opens with a header naming the project, branch, database, mode, and query, then prints:

- The initial result once, as a table.
- One entry per transaction, labeled with its transaction ID and a `+inserted ~updated -deleted` count, listing each changed row with its change type. A deleted row shows its last known values. A row that changes position in an ordered result shows as `↔ move` with its values, and the count ends with `↔` and the number of rows that moved.
- Connection state changes, such as connecting, live, and stale.

Every entry starts with a UTC timestamp. The server can send a complete `rows` replacement instead of incremental `changes` at any point, and then `realtime subscribe` prints the full result again. Some queries, such as ones with `ORDER BY`, can get a complete replacement for a change.

With `--changes`, it prints the raw events instead: a `rows` event with the complete current result, each row carrying a row ID, followed by `changes` events that list each change's type (`upsert`, `remove`, or `move`), row ID, and row. In table output, a `move` also shows `after_row_id`, the ID of the row it now follows, or `(head)` when it moved to the first position. A `rows` event replaces the full row set and invalidates earlier row IDs.

With `--output json`, each event is one JSON object per line. With `--output yaml`, each event is a separate YAML document. Each event has a `type` of `snapshot` (the default mode), or `rows` or `changes` (with `--changes`). Machine-readable output carries only the events: the header and connection states are terminal-only.

### Examples

Print the initial result, then a log of each transaction:

```bash
neon realtime subscribe "SELECT * FROM items"
```

Here, a row is inserted, another is renamed, the new row is deleted, and then one transaction inserts a row and renames another:

<details>

<summary>Show output</summary>

```text
Live query
Project   cool-darkness-12345678
Branch    dev (br-small-cell-a1b2c3d4)
Database  neondb
Mode      Materialized result
Query     SELECT * FROM items
[2026-10-13T13:49:35.168Z] Connecting…

[2026-10-13T13:49:35.725Z] Initial snapshot · 2 rows
ID  Name
1   apple
2   banana
[2026-10-13T13:49:35.726Z] Live — waiting for changes.

[2026-10-13T13:49:42.349Z] Transaction 15379 · +1 ~0 -0
Change    ID  Name
+ insert  3   cherry

[2026-10-13T13:49:45.992Z] Transaction 15380 · +0 ~1 -0
Change    ID  Name
~ update  2   blueberry

[2026-10-13T13:49:49.636Z] Transaction 15381 · +0 ~0 -1
Change    ID  Name
- delete  3   cherry

[2026-10-13T13:49:53.284Z] Transaction 15382 · +1 ~1 -0
Change    ID  Name
+ insert  4   date
~ update  1   apricot
```

</details>

Print the raw `rows` and `changes` events:

```bash
neon realtime subscribe --changes "SELECT * FROM items"
```

Here, a row is inserted, updated, and then deleted, one transaction each:

<details>

<summary>Show output</summary>

```text
Live query
Project   cool-darkness-12345678
Branch    dev (br-small-cell-a1b2c3d4)
Database  neondb
Mode      Raw changes
Query     SELECT * FROM items
[2026-10-13T13:48:40.801Z] Connecting…

[2026-10-13T13:48:41.461Z] Rows · 2 rows
Row ID                                                            Row
97254c8a1b75b7e21a05f98973614ea5af20ae9f4d481389eddb304c9b331ecf  {"id":1,"name":"apple"}
3045adcead9109b462b3c0e501e1c78c48b6cdbeb28bd3d3e01b83a61eaee302  {"id":2,"name":"banana"}
[2026-10-13T13:48:41.462Z] Live — waiting for changes.

[2026-10-13T13:48:48.072Z] Transaction 15370 · 1 upsert, 0 removals
Type    Row ID                                                            Row
upsert  1257d5759a0894512f6859dd60b504e69cbf6f8d9d4d977ee9b3b396661928bf  {"id":3,"name":"cherry"}

[2026-10-13T13:48:51.750Z] Transaction 15371 · 1 upsert, 0 removals
Type    Row ID                                                            Row
upsert  3045adcead9109b462b3c0e501e1c78c48b6cdbeb28bd3d3e01b83a61eaee302  {"id":2,"name":"blueberry"}

[2026-10-13T13:48:55.376Z] Transaction 15372 · 0 upserts, 1 removal
Type    Row ID
remove  1257d5759a0894512f6859dd60b504e69cbf6f8d9d4d977ee9b3b396661928bf
```

</details>

Show the database's full error when a query is rejected or fails:

```bash
neon realtime subscribe --debug "SELECT * FROM items"
```

Stream events as newline-delimited JSON, for example to pipe into another tool. Each event is a full snapshot of the result:

```bash
neon realtime subscribe "SELECT * FROM items ORDER BY id" --output json
```

```json
{"type":"snapshot","rows":[{"id":1,"name":"apple"},{"id":2,"name":"banana"}]}
{"type":"snapshot","rows":[{"id":1,"name":"apple"},{"id":2,"name":"banana"},{"id":3,"name":"cherry"}]}
{"type":"snapshot","rows":[{"id":1,"name":"apple"},{"id":2,"name":"blueberry"},{"id":3,"name":"cherry"}]}
```

---

## Related docs (Functions, storage and data)

- [functions](https://neon.com/docs/cli/functions)
- [triggers](https://neon.com/docs/cli/triggers)
- [buckets](https://neon.com/docs/cli/buckets)
- [data-api](https://neon.com/docs/cli/data-api)
- [neon-auth](https://neon.com/docs/cli/neon-auth)
- [credentials](https://neon.com/docs/cli/credentials)

---

Note for AI assistants (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/docs/cli/realtime"}` to https://feedback.neon.tech/ (no auth required).
