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

# Permissions and hierarchy

> How Bloom decides who can run a command, why role position matters, and how to fix permission errors.

Two separate things decide whether a Bloom command works: the permissions the person running it has, and the permissions and role position Bloom itself has. This page explains how Bloom checks both, what fake permissions do, and how to read a permission error.

## You need, and Bloom needs

Every command reference on this site states two things separately, because Bloom checks them separately:

* **You need:** the permission you must have to run the command. This is the command's user permission, or a special rule such as server owner only or Premium only.
* **Bloom needs:** the permission Bloom must have to carry the action out, plus the ability to send in the channel.

When a check fails, Bloom tells you which side is missing:

* *You need the following permissions: `...`* means you lack the user permission.
* *I need the following permissions: `...`* means Bloom lacks the bot permission.

Read the pronoun first. It points you at the fix: change the member's access, or change Bloom's.

## How Bloom checks your permission

For a command that requires a permission, Bloom allows you to run it if any of the following is true, in this order:

<Steps>
  <Step title="You are the server owner">
    The server owner passes every Bloom permission check.
  </Step>

  <Step title="You have Administrator">
    A member with Discord's Administrator permission passes every Bloom permission check.
  </Step>

  <Step title="You have the actual Discord permission">
    If the command needs Ban Members and you have Ban Members, you pass. When the command checks the channel, Bloom uses your effective permission in that channel, so a channel override that denies the permission there will block you even if your role grants it server wide.
  </Step>

  <Step title="You have a matching fake permission">
    If you do not have the real permission, Bloom checks whether you have been granted the matching [fake permission](#fake-permissions). If so, you pass Bloom's check.
  </Step>
</Steps>

If none apply, Bloom replies that you need the permission and does nothing.

## How Bloom checks its own permission

Separately, Bloom confirms it has the bot permission the command needs, in the channel where you ran it. Bloom respects channel overrides on itself, so a channel that denies Bloom Send Messages or Embed Links can block a command even when Bloom's role has those permissions elsewhere. When Embed Links is missing, some commands fall back to plain text; many actions simply cannot run without the right permission and Bloom says so.

## Role hierarchy

Permissions decide whether an action is *allowed*. Role position decides whether it is *possible*. Discord enforces hierarchy for both members and bots:

* Bloom can only act on a member, or add and remove a role, that sits **below Bloom's own highest role**. Place Bloom's role above every role it manages: the roles of members you moderate, level rewards, autoroles, and the mute and jail roles.
* A moderator cannot use Discord-level power over someone above them either. Even with Ban Members, Discord will not let a ban land on a member whose highest role is above the moderator's.

<Warning>
  A permission error is often really a hierarchy problem. If Bloom has Ban Members but "cannot" ban someone, check that Bloom's role is above that member's highest role.
</Warning>

## Fake permissions

Fake permissions let you grant a member or role the ability to use permission gated **Bloom commands** without giving them the real Discord permission. For example, you can let a trusted helper use Bloom's `warn` and `mute` without handing them Discord's Timeout Members permission across the whole server.

<Info>
  A fake permission satisfies **Bloom's own checks only**. It never grants any Discord API right. Bloom still performs the action with its own permissions and role position, and anything that depends on the member's real Discord rights is unaffected. Use fake permissions to delegate Bloom commands, not to replace Discord permissions.
</Info>

### Who manages them

Fake permissions are managed by the **server owner** and by **anti-nuke admins** (see below). Regular administrators do not manage the fake-permission list, though administrators already pass every Bloom check without needing one.

### What can receive them

* **A member** or **a role** can be granted fake permissions. A role grant applies to everyone with that role.
* The **@everyone** role cannot receive fake permissions.
* **Managed roles** (roles controlled by a bot or integration, including booster roles created by other apps) cannot receive fake permissions.

### The command

<ParamField path="fakepermissions <grant|remove|clear|list|config|perms>" type="Owner or anti-nuke admin">
  Manages fake permissions for roles and users. Aliases: `fakeperms`, `fp`, `fakeperm`.

  * `!fp grant <@role|@user> <permissions>` grants one or more permissions, comma or space separated.
  * `!fp remove <@role|@user> <permission>` removes a permission.
  * `!fp clear <@role|@user>` removes all of a target's fake permissions.
  * `!fp list <@role|@user>` shows what a target has.
  * `!fp config` lists every fake permission set on the server.
  * `!fp perms` lists the permission names you can grant.
</ParamField>

```text Grant a role two permissions theme={null}
!fp grant @Helper ban, timeout
```

Bloom confirms `Granted to Helper: Ban Members, Timeout Members`. Members with the Helper role can now run Bloom's ban and timeout commands. Permission names accept friendly aliases, so `ban` works for Ban Members and `timeout` for Timeout Members. The full list of names and aliases is in the [Permission reference](/reference/permissions#fake-permissions).

## Server owner versus anti-nuke admin

Bloom recognizes two distinct kinds of elevated access. They are not the same thing.

|                                                     | Server owner             | Anti-nuke admin                               |
| --------------------------------------------------- | ------------------------ | --------------------------------------------- |
| Who                                                 | The Discord server owner | Members added to Bloom's anti-nuke admin list |
| Set by                                              | Discord                  | The server owner only                         |
| Passes Bloom permission checks                      | Yes, all of them         | No, only the commands below                   |
| Can run `antinuke`, `staffroles`, `fakepermissions` | Yes                      | Yes                                           |
| Can run `antinuke setup` and manage the admin list  | Yes                      | No                                            |

An anti-nuke admin is a Bloom concept for delegating the security commands to trusted people without making them a Discord administrator. It does not grant Discord permissions and does not, on its own, let someone run ordinary moderation commands. Only the server owner can run `antinuke setup` or add and remove anti-nuke admins.

## Diagnose "permission denied"

Work through these in order. They go from cheapest to check to most involved.

<AccordionGroup>
  <Accordion title="Bloom says: You need the following permissions">
    You are missing the user permission. Confirm the member has the Discord permission the command names, or grant them the matching [fake permission](#fake-permissions). Remember that a channel override can deny a permission in one channel only.
  </Accordion>

  <Accordion title="Bloom says: I need the following permissions">
    Bloom is missing the bot permission. Give Bloom's role that permission, and check the channel is not denying it there. Send Messages and Embed Links are the two that most often block a reply.
  </Accordion>

  <Accordion title="The permission is present but the action still fails on one member">
    This is almost always hierarchy. Bloom, or the acting moderator, must have a higher top role than the target. Move Bloom's role above the roles it needs to manage.
  </Accordion>

  <Accordion title="A security command is refused">
    `antinuke`, `staffroles`, and `fakepermissions` are limited to the server owner and anti-nuke admins. `antinuke setup` and managing the admin list are limited to the owner alone.
  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Permission reference" icon="shield-halved" href="/reference/permissions">
    The permission glossary, the fake-permission names, and the dashboard access matrix.
  </Card>

  <Card title="Invite and first setup" icon="rocket" href="/getting-started/first-setup">
    Add Bloom and place its role before you configure anything else.
  </Card>

  <Card title="Dashboard access" icon="sliders" href="/getting-started/dashboard">
    How dashboard access maps to these same permissions.
  </Card>

  <Card title="Using prefix commands" icon="terminal" href="/getting-started/commands">
    How to read a command's "You need" and "Bloom needs".
  </Card>
</CardGroup>
