# Neon CLI command: roles

The `roles` command lists, creates, and deletes roles in a Neon project from the terminal. For information about roles in Neon, see [Manage roles](/guides/manage-operate-manage-roles). If `--project-id` is omitted, the CLI resolves it from your [context file](/guides/apis-sdks-cli-link), auto-selects when your account has only one project, and otherwise asks you to pass `--project-id`.

Subcommands: [create](#neon-roles-create), [delete](#neon-roles-delete), [list](#neon-roles-list)

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

```title="Output"
┌────────┬──────────────────────┐
│ Name   │ Created At           │
├────────┼──────────────────────┤
│ daniel │ 2023-06-19T18:27:19Z │
└────────┴──────────────────────┘
```

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

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

:::accordion{title="Show output"}
```json
[
  {
    "branch_id": "br-odd-frog-703504",
    "name": "daniel",
    "protected": false,
    "created_at": "2023-06-28T10:17:28Z",
    "updated_at": "2023-06-28T10:17:28Z"
  }
]
```
:::

## neon roles create

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

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

| Option         | Description                                  | Type    | Default | Required |
| -------------- | -------------------------------------------- | ------- | ------- | -------- |
| `--name`       | Role name                                    | string  | —       | Yes      |
| `--no-login`   | Create a passwordless role that cannot login | boolean | —       | No       |
| `--branch`     | Branch ID or name                            | string  | —       | No       |
| `--project-id` | Project ID                                   | string  | —       | No       |

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

```title="Output"
┌───────┬──────────────────────┐
│ Name  │ Created At           │
├───────┼──────────────────────┤
│ sally │ 2023-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
```

```title="Output"
┌───────┬──────────────────────┐
│ Name  │ Created At           │
├───────┼──────────────────────┤
│ sally │ 2023-06-20T00:43:17Z │
└───────┴──────────────────────┘
```

## Related pages

- [Neon CLI command: snapshots](./apis-sdks-cli-snapshots.md)
- [Neon CLI command: diff](./apis-sdks-cli-diff.md)
- [Neon CLI command: projects](./apis-sdks-cli-projects.md)
- [Neon CLI command: branches](./apis-sdks-cli-branches.md)
- [Neon CLI command: databases](./apis-sdks-cli-databases.md)
- [Neon CLI command: operations](./apis-sdks-cli-operations.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.