> This page location: APIs & SDKs > CLI > Projects and branches > roles
> 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 roles` CLI command lists, inspects, creates, and deletes database roles in a Neon project and resets their passwords. Its subcommands target a specific branch or the project default. Use it when you need to add an admin or a scoped read-only or read-write role, create a passwordless role with `--no-login`, rotate a password, or remove a role from the command line. Role names are capped at 63 bytes; commands require the Neon CLI and either browser-based auth or an API key.

# Neon CLI command: roles

List, inspect, create, and delete database roles, and reset their passwords

Last updated: 2026-11-05

From the terminal, the `roles` command lists, inspects, creates, and deletes roles in a Neon project, and resets their passwords. It's also available as [`neon postgres roles`](https://neon.com/docs/cli/postgres#roles). For information about roles in Neon, see [Manage roles](https://neon.com/docs/manage/roles). If `--project-id` is omitted, the CLI resolves it from your [context file](https://neon.com/docs/cli/link), auto-selects when your account has only one project, and otherwise asks you to pass `--project-id`.

Subcommands: [create](https://neon.com/docs/cli/roles#create), [delete](https://neon.com/docs/cli/roles#delete), [get](https://neon.com/docs/cli/roles#get), [list](https://neon.com/docs/cli/roles#list), [reset-password](https://neon.com/docs/cli/roles#reset-password)

## neon roles list

Lists roles. If you don't specify a branch ID or name with `--branch`, the command targets the project's default branch. This applies to all `roles` subcommands.

```bash
neon roles list [options]
```

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

List roles with the default `table` output format:

```bash
neon roles list
```

```text filename="Output"
Roles on main
Name          Created At
neondb_owner  2026-06-19T18:27:19Z
```

The table is titled with the branch the roles belong to, so you can tell at a glance which branch you're looking at.

List roles with the `--output` format set to `json`:

```bash
neon roles list --output json
```

<details>

<summary>Show output</summary>

```json
[
  {
    "branch_id": "br-odd-frog-123456",
    "name": "neondb_owner",
    "protected": false,
    "created_at": "2026-06-28T10:17:28Z",
    "updated_at": "2026-06-28T10:17:28Z"
  }
]
```

</details>

## neon roles create

Creates a role. The role name cannot exceed 63 bytes.

```bash
neon roles create [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--access` | admin joins neon\_superuser. read\_only grants SELECT; read\_write adds INSERT, UPDATE, DELETE. Scoped roles are created with SQL as the database owner and cover tables that owner owns, now and later Possible values: `admin`, `read_only`, `read_write` | string | `admin` | No |
| `--database` | Database a read\_only or read\_write role is scoped to. Defaults to the branch's only database | string | — | No |
| `--name` | Role name | string | — | Yes |
| `--no-login` | Create a passwordless role that cannot login | boolean | — | No |
| `--schema` | Schema a read\_only or read\_write role can use. Repeat for more. Defaults to public | array | — | No |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |

```bash
neon roles create --name sally
```

```text filename="Output"
Role created on main
Name        sally
Password    npg_aBcDeFgH1234
Created At  2026-06-20T00:43:17Z
```

The create output includes the password Neon generated for the new role. Neon returns it only once, so copy it now, or run [`neon roles reset-password`](https://neon.com/docs/cli/roles#reset-password) later to get a new one. A `--no-login` role has no password, so no `Password` row appears.

By default, a new role joins `neon_superuser`, which makes it an admin on every database. Pass `--access read_only` for a role that can only read, or `--access read_write` for one that can also insert, update, and delete rows. A scoped role applies to one database. Name it with `--database`, or leave it out when the branch has only one. Its access is limited to the `public` schema unless you pass `--schema`, and to tables owned by that database's owner, including tables the owner creates later.

```bash
neon roles create --name reporting --access read_only
```

```bash
neon roles create --name app_writer --access read_write --database neondb --schema public
```

`--database` and `--schema` work only with `--access read_only` or `--access read_write`.

## neon roles get

Shows a role's details. The `<role>` is the role name.

```bash
neon roles get <role> [options]
```

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

```bash
neon roles get reporting
```

```text filename="Output"
Name                   reporting
Branch ID              br-lively-sunset-123456
Protected              false
Authentication Method  password
Created At             2026-11-05T14:24:30Z
Updated At             2026-11-05T14:24:30Z
```

## neon roles reset-password

Generates a new password for a role and prints it. The old password stops working. By default the command waits until the compute applies the new password, so you can connect with it right away. With `--no-wait`, it returns as soon as the API accepts the reset.

```bash
neon roles reset-password <role> [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--wait` | Wait until the compute applies the new password. Use --no-wait to return as soon as the API accepts the reset | boolean | `true` | No |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |

```bash
neon roles reset-password sally
```

```text filename="Output"
Password reset for sally on main
Name        sally
Password    npg_aBcDeFgH1234
Created At  2026-06-20T00:43:17Z
```

## neon roles delete

Deletes a role. The `<role>` is the role name.

```bash
neon roles delete <role> [options]
```

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

```bash
neon roles delete sally
```

```text filename="Output"
Role deleted from main
Name        sally
Created At  2026-06-20T00:43:17Z
```

---

## Related docs (Projects and branches)

- [snapshots](https://neon.com/docs/cli/snapshots)
- [diff](https://neon.com/docs/cli/diff)
- [projects](https://neon.com/docs/cli/projects)
- [branches](https://neon.com/docs/cli/branches)
- [postgres](https://neon.com/docs/cli/postgres)
- [databases](https://neon.com/docs/cli/databases)
- [operations](https://neon.com/docs/cli/operations)

---

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/roles"}` to https://feedback.neon.tech/ (no auth required).
