// Guide
Command Permissions
Per-command role allowlists enforced on every command in your guild — decide exactly who can run what, without touching Discord's native permission system.
Every StarBot command in your guild passes through a per-guild role allowlist before it runs. Out of the box, each command uses a sensible default (member commands are open to everyone; admin commands require the appropriate Discord permission). The permissions system lets you override that default per command: open a command up to everyone, restrict it to specific roles, or disable it entirely.
You can manage overrides from two places — the Permissions tab on your guild's dashboard, or the /config-permsadmin command in Discord. Both write to the same allowlist.
Members with the Discord Administrator permission bypass the allowlist entirely — you can never lock an admin out of a command. This is a safety valve: even if you accidentally deny every role on /config-perms itself, an Administrator can still run it and undo the change.
How the check works
When a member runs a command, the bot evaluates in order:
- Is the user a Discord Administrator? If yes, the command runs. Always.
- Does the command have an override in this guild? If yes, the override decides: the user needs at least one allowed role (or the command is disabled for everyone).
- No override? The command falls back to its built-in default — open to members, or gated behind the Discord permission it normally requires.
Changes apply on the next command invocation — there is no bot restart, no re-sync, no propagation delay. Edit an override, and the very next time someone runs that command the new rule is enforced.
The Permissions tab
Open your guild at /dashboard, then switch to the Permissions tab. It lists every command the bot registers, with a search box to filter by name and an "Only commands with overrides" checkbox to see just the commands you've customized.
| Command | Category | Status | Default |
|---|---|---|---|
| /config-orders | Orders | Specific roles: @Logistics Lead | Admin only |
| /config-perms | Permissions | Default | Admin only |
| /order | Orders | Everyone | Members |
| /aistory | AI Story | Disabled | Members |
Each row shows the command, its category, its current Status (Default, Everyone, Specific roles, or Disabled), and what the built-in Default would be. Click the pencil icon on a row to open the edit modal.
The edit modal
The modal offers three modes plus a reset:
- Everyone — any member can run the command, regardless of Discord permissions.
- Specific roles — only members holding at least one of the checked roles can run it. A role checkbox list appears when you pick this mode.
- Disable for everyone — nobody can run the command (except Discord Administrators, who always pass).
- Reset to default — removes the override entirely; the command goes back to its built-in behavior.
Setting an override
- 1Open the Permissions tab on your guild's dashboard page.
- 2Find the command — type in the search box, or tick Only commands with overrides to review existing customizations.
- 3Click the pencil on the command's row to open the edit modal.
- 4Pick a mode. Choose Everyone, Specific roles (then check the roles that should have access), or Disable for everyone.
- 5Click Save Changes. The rule is live on the next invocation of that command — no restart needed.
Managing from Discord
The /config-perms allow_role · deny_role · reset · listadmin command mirrors the dashboard:
config-perms allow_role command:/config-orders role:@Logistics Leadallow_role command: role:— add a role to the command's allowlist (switching it to specific-roles mode if it wasn't already).deny_role command: role:— remove a role from the allowlist.reset command:— clear the override and return the command to its default.list— show every command with an active override in this guild.
Dashboard and Discord edits land in the same place, so you can grant a role from Discord mid-session and later review it in the Permissions tab.
Practical examples
Open orders to everyone, lock down order admin. Leave /order at its default (members can use it), but set /config-orders to Specific roles with only your @Logistics Lead role checked. Members place orders; only logistics leadership changes the category, role pings, and org-funding settings.
Restrict a member command to a trusted tier. /aistory start is open to members by default. If story sessions keep getting started as a joke, set it to Specific roles → @Storytellers. Everyone else gets a permission-denied reply; your storyteller role keeps full access.
Retire a command without uninstalling anything. Not a fleet-focused server? Set /hangar (or any command your community doesn't need) to Disable for everyone. It stays registered but rejects every invocation — and one click on Reset to default brings it back later.
An Everyone override lets members run a command that normally requires a Discord permission — including admin configuration commands. Double-check before opening up anything with config in its name. Conversely, Specific roles blocks members who would normally qualify via Discord permissions (Administrators excepted).
Troubleshooting
"A member with the right role still can't run the command." Check the row's Status in the Permissions tab — the command may be set to Disable for everyone, or the override may list a different role than you think. Also confirm the member actually holds the role (not just a similarly named one).
"I locked myself out of a config command." You didn't — Discord Administrators always bypass the allowlist. Have an Administrator run the command or fix the override in the dashboard.
"My change didn't take effect." Overrides apply on the next invocation. If a member ran the command before you saved, that invocation used the old rule; the next one uses the new rule. There is no caching to wait out.
Related
- Dashboard tour — where the Permissions tab lives among the other tabs.
- Command reference — the full command catalogue with default tiers and scopes.