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

# Roles

> Headless separates automatically assigned roles, member self-service menus, and reaction-to-role mappings.

## Choose the workflow

Auto Role configures join-time roles for humans and bots, as well as panels where members can choose roles. See [Auto roles](/docs/en/server/roles/auto.md) for join assignments and [Self-assignable roles](/docs/en/server/roles/self-assignable.md) to publish and maintain selectors. Reaction Roles maps message reactions to roles; [Booster Roles](/docs/en/server/roles/booster.md) manages boost-related roles and announcements.

## Permissions

Discord role hierarchy still applies: the bot role must be above every role it grants or removes. Administrative actions also enforce each module's required permissions.

## Restore eligible roles

`.restore <user> [source] [reason]` attempts to return roles Headless recorded as removed. Prefix aliases are `.rr`, `.rs`, `.res`, and `.restaurar`. `/restore` and `/rs` offer the same `auto`, `jail`, `logs`, and `history` sources; the slash option is named `source`, with `history` shown as “Historial” in the picker.

In `auto` mode, Headless checks roles saved by Jail, then recent role changes in Logs/Cases, then role names in User History. Logs and Cases are each scanned up to 4,000 recent entries; for each role, only its latest event is considered, and it is proposed only when that event was a removal. User History resolves names case-insensitively but skips duplicate names or deleted roles. An explicit source limits the lookup to that source. If there is no safe source, the command does not guess.

When a Jail source is available, Headless also attempts to remove the Jail role. The Jail record is cleared only after the Discord operations finish without an error; if Discord fails during the changes, the record is retained for investigation or a retry. Up to 25 eligible roles can be restored. Roles that already exist on the member, were deleted, are managed by an integration, or fail current validation are skipped.

The prefix command requires `Manage Roles` from both the caller and Headless. Discord marks `/restore` and `/rs` with `Manage Roles` as their default permission; Headless also needs `Manage Roles` and validates the actor, target member, and each role against current hierarchy. It cannot modify `@everyone`, managed roles, the server owner, or roles at or above the actor or bot; an administrator, server owner, or Headless owner may restore a role with `Administrator`.

```headless-command Syntax theme={null}
.restore [user_query] [rest]
```

```headless-command Example theme={null}
.restore @Member auto Returning from Jail
```

Also works: `.restore @Member logs Reviewed role recovery`

```headless-command Syntax theme={null}
/restore user:<user> [source:<source>] [reason:<reason>]
```

```headless-command Example theme={null}
/restore user:@Member source:auto reason:Returning from Jail
```

```headless-command Syntax theme={null}
/rs user:<user> [source:<source>] [reason:<reason>]
```

```headless-command Example theme={null}
/rs
```

**1. Check the available source**

Use `auto` to let Headless try the sources in order, or choose `jail`, `logs`, or `history` to limit the lookup. History is server-scoped; roles are not matched by fuzzy similarity.

**2. Run the restoration**

Mention the member or use their ID. Add a reason so the operation is recorded in its case and log entry.

**3. Review the result before retrying**

Check which roles were restored or skipped, along with the case history and logs. A Discord error can occur after an earlier operation has already succeeded.

> **What can each source recover?**
>
> `jail` uses roles saved in the active Jail record; `logs` uses recent removals identified by role ID; `history` resolves names saved in User History when there is exactly one match. `auto` tries these three sources in that order.

> **Why was a role skipped, or Jail not cleared?**
>
> The role may no longer exist, the member may already have it, an integration may manage it, or current hierarchy/permissions may prevent changes. If a Discord call fails, Headless reports the error and retains the Jail record; check the member's actual state before retrying.

> [!WARNING]
>
> Restoration can skip roles that no longer exist or cannot be managed; a Discord failure can leave a partial result. Review the summary, cases, and logs before running restoration again.

**Note:**

Each workflow has its own settings, permissions, and limits.

## Related pages

* [Auto roles](/docs/en/server/roles/auto.md)
* [Self-assignable roles](/docs/en/server/roles/self-assignable.md)
* [Reaction Roles](/docs/en/server/roles/reaction-roles.md)
* [Booster roles](/docs/en/server/roles/booster.md)


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