> For the complete documentation index, see [llms.txt](https://dreamliner.gitbook.io/dreamliner-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dreamliner.gitbook.io/dreamliner-docs/docs/plugins/autorole.md).

# Autorole plugin

Automatically assigns roles when members join your server. Each role can have its own delay before it is applied.

## Configuration

```yaml
plugins:
  autorole:
    enabled: true
    config:
      roles:
        - role: "1234567890123456789"
          delay_ms: 0
        - role: "9876543210987654321"
          delay: "30s"
```

| Field      | Description                                                                                             |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| `role`     | Role snowflake ID to assign                                                                             |
| `delay_ms` | Wait time in milliseconds before this role is assigned (`0` = immediate)                                |
| `delay`    | Optional duration string (`30s`, `5m`, `1h`, `1d`, `1w`) for this role; overrides `delay_ms` when valid |

You can also use a plain role ID string for immediate assignment:

```yaml
roles:
  - "1111111111111111111"
  - role: "2222222222222222222"
    delay: "1m"
```

Set `enabled: false` on the plugin section to turn autorole off without removing your role list.

## Commands

| Command            | Permission   | Description                                   |
| ------------------ | ------------ | --------------------------------------------- |
| `/autorole add`    | `can_add`    | Open a form to pick a role and optional delay |
| `/autorole remove` | `can_remove` | Remove a role from the autorole list          |
| `/autorole list`   | `can_list`   | List configured autoroles                     |

Changes from commands are saved to your server config (same YAML section as manual edits). Use `/config download` to export the updated config.

Default permission grants (level **50+**):

```yaml
overrides:
  - level: ">=50"
    config:
      can_add: true
      can_remove: true
      can_list: true
```

## Requirements

* The bot needs the **Manage Roles** permission.
* The bot's highest role must be **above** every autorole role.
* Managed roles (integrations, bot roles, etc.) cannot be assigned and are skipped.
* Bots joining the server are ignored.

## Examples

Welcome role immediately, verified role after 30 seconds:

```yaml
plugins:
  autorole:
    config:
      roles:
        - role: "1111111111111111111"
          delay_ms: 0
        - role: "2222222222222222222"
          delay: "30s"
```

Or configure in Discord:

1. `/autorole add` → select the welcome role, delay `0`
2. `/autorole add` → select the verified role, delay `30s`
3. `/autorole list` to review


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://dreamliner.gitbook.io/dreamliner-docs/docs/plugins/autorole.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.