# Chalk CLI Reference: Team & Roles
source: https://docs.chalk.ai/cli#team-&-roles

List the users on your team and manage the roles they hold, either in a single environment or team-wide. Role changes are recorded in the [audit log](https://docs.chalk.ai/cli?command=audit_list), and the required `team.add` and `team.admin` permissions can be granted to a service token so an external tool can manage roles programmatically.

## `chalk user list`
source: https://docs.chalk.ai/cli?command=user_list

```bash
chalk user list
```

Use the `list` command to see the users on your team, along with the roles they hold team-wide and in the active environment.

The user ids printed here are the ones accepted by [`chalk user set-role`](https://docs.chalk.ai/cli?command=user_set-role).

**Example**

```
$ chalk user list
 Email                 Name        User ID                       Environment Roles  Team Roles
──────────────────────────────────────────────────────────────────────────────────────────────
 alice@example.com     Alice       cl0wpcey0770609l56lazvc52     admin              team_owner
 bob@example.com       Bob         900nw89h0wz0613l57la8v958     viewer
```

## `chalk user roles`
source: https://docs.chalk.ai/cli?command=user_roles

```bash
chalk user roles
```

Use the `roles` command to list the roles that can be assigned to a user, including any custom roles defined by your team.

The ids printed here are the ones accepted by [`chalk user set-role`](https://docs.chalk.ai/cli?command=user_set-role). To see the individual permissions that can be granted to a service token, use [`chalk permissions`](https://docs.chalk.ai/cli?command=permissions) instead.

**Example**

```
$ chalk user roles
 ID              Name            Default  Description
─────────────────────────────────────────────────────────────────────────────────
 viewer          Viewer          true     Read-only access
 data_scientist  Data Scientist           Query features and datasets
 developer       Developer                Deploy and manage feature pipelines
 admin           Admin                    Full access to an environment
 owner           Owner                    Full access, including billing
```

## `chalk user set_role`
source: https://docs.chalk.ai/cli?command=user_set_role

```bash
chalk user set-role <user> <role>
```

Use the `set-role` command to grant a user a role, either in the active environment or across the whole team.

This is the programmatic equivalent of changing a member's role from the team settings page, so it can be driven from an external tool holding a service token rather than by a human in the dashboard. Every call is recorded in the audit log along with the acting agent, the target user, and the role, so the change is reviewable after the fact with [`chalk audit list`](https://docs.chalk.ai/cli?command=audit_list).

The role that takes effect is the most recently assigned one, so running this command repeatedly both elevates and de-escalates a user -- assigning `viewer` to a user who currently holds `admin` leaves them with `viewer`.

The caller needs the `team.add` permission to set an environment-scoped role, and `team.admin` to set a team-scoped role. Both permissions can be granted to a service token, which is how an automated tool should authenticate.

**Arguments**

- `user` (string)
  The user to assign the role to, given as either a user id or an email address.
- `role` (string)
  The role to assign, given as a role id such as `viewer`, `developer`, `admin`, or `owner`. Run [`chalk user roles`](https://docs.chalk.ai/cli?command=user_roles) to list the roles available to your team, including custom roles.

**Flags**

- `--scope <environment>` (string, default `environment`)
  Scope of the assignment. `environment` (the default) grants the role only in the active environment. `team` grants a team-wide role that applies outside of any single environment.
- `-y, --yes <yes>` (bool, default `false`)
  Skip the confirmation prompt. Implied when stdin is not a terminal, so scripts never need to pass it.

**Example**

```
$ chalk user set-role alice@example.com admin
✓ Set role 'admin' for alice@example.com in environment 'prod'

$ chalk user set-role cl0wpcey0770609l56lazvc52 viewer
✓ Set role 'viewer' for cl0wpcey0770609l56lazvc52 in environment 'prod'

$ chalk user set-role alice@example.com team_owner --scope team
✓ Set team-scoped role 'team_owner' for alice@example.com
```
