> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.petto.sbs/llms.txt
> Use this file to discover all available pages before exploring further.

# Role Commands and Bulk Roles

> Give, remove and manage roles with /role, run a role for many members at once with a preview, a progress card, pause and cancel, and do the same from the dashboard Roles page.

## Overview

`/role` (and `!role`) manages roles one by one and in bulk. It needs **Manage Roles**, the mass subcommands need **Administrator**, and Petto's own role must be above every role it gives or takes away ([permissions and hierarchy](https://wiki.petto.sbs/concepts/permissions-and-hierarchy.md)). Roles an integration manages and `@everyone` cannot be given by anyone.

```javascript Syntax theme={null}
!role add <user> <roles> [reason]
!role remove <user> <roles> [reason]
!role temp <user> <role> <duration>
!role temp-list
!role all <role> [remove] [preview] [without] [reason]
!role humans <role> [remove] [preview] [reason]
!role has <filter_role> <target_role> [remove] [without] [preview] [reason]
!role bots <role> [preview] [reason]
!role bots-remove <role> [preview] [reason]
!role job [status|pause|resume|cancel]
!role cancel
```

```javascript Example theme={null}
!role @Mia Member
!role temp @Mia VIP 3d
!role all @Member
!role humans @Newcomer preview
!role has @Veteran @Elder --joined_before 365d
!role all @Old remove --max_roles 1 cleaning up the server
!role job pause
```

The same commands exist as slash commands (`/role all`, `/role job`, and so on). Everything the word `!role` can do is also under `/role`.

## One role at a time

* `add` and `remove` take one or more roles (mentions, IDs or names). Petto says which ones it could not give and why, in your language: the role is above Petto, above you, or managed by an integration.
* `temp` gives a role for a while (up to one year) and Petto takes it away when the time is up. If the member already had the role, Petto says so: it will still be taken away. `temp-list` shows who has a temporary role and when it ends.
* A temporary role that you take away by hand, or give for good with `add`, is forgotten, so the timer never removes it later.
* `group create|delete|view|list|give|take` keeps named sets of roles to give or take in one go.
* `create`, `delete`, `edit`, `color`, `icon`, `mentionable`, `hoist`, `topcolor`, `list` and `in` manage the roles themselves.

## Bulk roles

`all`, `humans`, `has`, `bots` and `bots-remove` give or take away one role for many members. They run as a **job**: the same engine the dashboard Roles page uses.

* **One job per server at a time.** A new one waits until the running one ends.
* **Safe on big servers.** Members are read in pages of 1000, never all at once, and Discord's own limit paces the changes.
* **It survives a restart.** If Petto restarts while a job runs, the job goes on from the member where it was.
* **A card follows it** in the channel: members checked, changed, already fine and failed, the time left, and what to do to pause or cancel it. When it ends the card shows the result and how long it took.
* **It stops by itself** if Discord refuses 15 members in a row, which means Petto lost the permission or the role moved above its own.
* A member who left while the job ran is counted as already fine, not as a failure.

### Options

| Option | What it does |
| - | - |
| `remove` | Take the role away instead of giving it. |
| `preview` | Only count who would change. Nobody is touched. |
| `without` | (`has` only) the members who do **not** have the filter role. |
| `joined_after`, `joined_before` | A day like `2025-03-01` (from midnight UTC) or a time back like `30d`. With the prefix write them as `--joined_after 30d`. |
| `min_roles`, `max_roles` | Only members with at least or at most this many roles, without counting `@everyone`. `--max_roles 0` picks members with no roles. |
| `reason` | Shown in the audit log with the job number. With the prefix it is the rest of the message. |

With the prefix the name of an option alone turns it on: `!role all @Member remove preview`. `!role humans @Member true` still works.

### Preview, status, pause and cancel

Run the command with `preview` first to see how many members would change, then run it again without it. `!role job` shows the running job, or the last one, and the last few before it. `!role job pause` and `!role job resume` stop and go on, and `!role job cancel` (or `!role cancel`) stops it for good: the member in progress finishes and nothing else is changed. Anyone with Administrator can control a job, including one started from the dashboard.

> [!WARNING]
>
> Be careful with roles that give **Administrator**, Manage Server, Manage Roles, Ban Members or similar permissions: giving them to many members at once is hard to undo. The card warns you, and the dashboard asks you to confirm.

## Join roles and sticky roles

Both live under `/role`:

* `/role join add|remove|list|clear|apply` is [`!joinrole`](https://wiki.petto.sbs/onboarding/join-roles): roles given when a member joins. `apply` gives a join role now to the members who are already in the server.
* `/role sticky enable|disable|status` is [`!stickyroles`](https://wiki.petto.sbs/automation/sticky-roles): Petto gives back a member's roles when they return.

The old `!joinrole`, `!jr`, `!stickyroles`, `!sr` and `!greet joinrole` keep working.

## The Roles page of the dashboard

**Dashboard → Automation → Roles** does the same from the browser, and it is easy to use on a phone.

1. Choose the **role** and whether to **assign** or **remove** it. Roles Petto cannot give are greyed out with the reason. A role with powerful permissions shows a warning and a box to confirm.
2. Choose **who**: all members, humans or bots, a join date range (real date pickers, plus buttons for the last 7, 30 or 90 days and for older than 30 days, 90 days or a year), how many roles they have, roles they must have or must not have (any or all of them), and whether to skip members who have not accepted the rules yet.
3. Add a **reason** for the audit log and, if you want, a channel to be told when it ends.
4. Press **Preview** to see how many members would change, or **Start**. After a preview, **Run it for real** starts the same job.
5. Follow the job: a progress bar, members checked, changed, already fine and failed, the time left, and **Pause**, **Resume** and **Cancel**. The page keeps itself up to date.
6. **Recent jobs** lists the last ones with their result and, if a job failed, why: Petto is missing Manage Roles, the role was deleted, it is managed, it is above Petto, and so on.

The page and Discord share the same job, so you can start in one and pause or cancel in the other.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.