---
layout: docs
page_title: roles list - Command
description: |-
  The "roles list" command lists the roles within a given scope or resource.
---

# roles list

Command: `boundary roles list`

The `boundary roles list` command lets you list the Boundary roles within a given scope or resource.

## Example

This example lists all roles within the scope `s_1234567890`.
The `recursive` option means Boundary runs the operation recursively on any child scopes, if applicable:

```shell-session
$ boundary roles list -scope-id s_1234567890 -recursive
```

## Usage

<CodeBlockConfig hideClipboard>

```shell-session
$ boundary roles list [options] [args]
```

</CodeBlockConfig>

### Command options

- `-filter=<string>` - If set, filters the list operation before the results are returned.
The filter operates against each item in the list.
We recommend that you use single quotes, because the filters contain double quotes.
Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details.
- `-recursive` - If set, runs the list operation recursively on any child scopes, if the type supports it.
The default value is `false`.
- `-scope-id=<string>` - The enclosing scope from which you want to list the roles.
The default value is `global`.
You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable.

@include 'cmd-option-note.mdx'