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

# Linked Roles

> Linked roles are secondary or cosmetic roles automatically assigned or removed alongside a base role.

While base roles determine a staff member's position in the hierarchy, **Linked Roles** are additional roles that allow you to give your staff members the extra permissions they need to actually do their job or participate in the community.

When a user is hired or promoted into a base role, Nocturne will automatically assign all of its linked roles. When they are fired or demoted out of it, Nocturne will automatically remove them.

***

<h2 id="uses">
  Common Uses for Linked Roles
</h2>

If you are wondering why you might need this feature, here are the most common ways servers utilise linked roles:

* **Permission Tokens**
  * Many servers use separate roles used exclusively for permissions (e.g., a "Ban Perms" or "Kick Perms" role, especially if your moderation bot requires them). This sometimes may not even have the actual Discord permission associated with it, thus maintaining consistency of performing actions on a user with a bot.
* **Cosmetics & Access**
  * These are roles that grant access to hidden channels or provide other benefits (e.g., "Staff Lounge Access", "Staff Giveaway Bonus").
* **Secondary Roles**
  * These can be notification or operational roles crucial for the duties (e.g., "Raid Alert Ping", "Ticket Support Ping", "Log Access").

***

<h2 id="linked-role-add">
  Adding a Linked Role
</h2>

To automate a secondary role, you must attach it to a specific base role within your tree.

<Badge color="red" size="sm">User: Manage Server</Badge>

<Tabs>
  <Tab title="Command" icon="code-simple">
    ```text Command theme={null}
    /tree linked-role add <tree> <base> <role>
    ```

    * `<base>`: The primary hierarchy role the user holds.
    * `<role>`: The secondary role you want Nocturne to assign automatically.

    ```text Example theme={null}
    /tree linked-role add tree:Moderation base:@Moderators role:@Raid Alert
    ```
  </Tab>

  <Tab title="Visual Output" icon="image">
    <img src="https://mintcdn.com/nocturneidle/2-3YwYR-s24LwC-D/images/Tree-Linked-Role-Add.png?fit=max&auto=format&n=2-3YwYR-s24LwC-D&q=85&s=1560043182d4ba60cb24254957c19645" alt="Tree Linked Role Add" title="Tree Linked Role Add" className="mx-auto" style={{ width:"80%" }} width="566" height="231" data-path="images/Tree-Linked-Role-Add.png" />
  </Tab>
</Tabs>

<Note>
  The base role you specify must already be configured in the tree you are going to use it in.
</Note>

<Note>
  When you run `/tree view [tree]` (with the `[tree]` parameter), you will see the linked roles as subpoints below the associated base role.

  <img src="https://mintcdn.com/nocturneidle/2-3YwYR-s24LwC-D/images/Tree-View-Linked-Role.png?fit=max&auto=format&n=2-3YwYR-s24LwC-D&q=85&s=57db876801cd3f0c4583f1e502891b80" alt="Tree View: Linked Role" title="Tree View: Linked Role" className="mx-auto" style={{ width:"50%" }} width="451" height="382" data-path="images/Tree-View-Linked-Role.png" />

  *Here, **@Staff Lounge Access** is a Linked Role for **@Trainee Mod**, while **@Raid alert** and **@Ticket Support Access** are Linked Roles for **@Moderators***
</Note>

***

<h2 id="linked-role-remove">
  Removing a Linked Role
</h2>

If you no longer want a secondary role to be assigned automatically, you can unlink it.

<Badge color="red" size="sm">User: Manage Server</Badge>

<Tabs>
  <Tab title="Command" icon="code-simple">
    ```text Command theme={null}
    /tree linked-role remove <tree> <base> <role>
    ```

    ```text Example theme={null}
    /tree linked-role remove tree:Moderation base:@Moderators role:@Giveaway Bonus
    ```
  </Tab>

  <Tab title="Visual Output" icon="image">
    <img src="https://mintcdn.com/nocturneidle/2-3YwYR-s24LwC-D/images/Tree-Linked-Role-Remove.png?fit=max&auto=format&n=2-3YwYR-s24LwC-D&q=85&s=673d7ea8a39b61c6ac004df464c43293" alt="Tree Linked Role Remove" title="Tree Linked Role Remove" className="mx-auto" style={{ width:"80%" }} width="585" height="241" data-path="images/Tree-Linked-Role-Remove.png" />
  </Tab>
</Tabs>

<Note>
  Unlinking a role only stops Nocturne from automating it in the future. It will **not** automatically strip the role from users who already have it, and neither will it delete the role from the server.
</Note>

***

<h2 id="persistence">
  Linked Role Persistence
</h2>

Linked Roles can be configured to either stay as a user gets promoted, or they can be configured to be role-specific.

There is a configuration setting called **persistence,** which dictates this behaviour.

* If enabled, when a user is promoted to a new base role, they will keep the linked roles they got from the previous base roles.
* If disabled, when a user is promoted, they automatically lose the linked role associated with the previous base role and gain the linked roles associated with their new role.

<Note>
  *Read more about how to toggle this behaviour on the [Configuration Overview](/commands/config/overview) page.*
</Note>