Commands

All commands are registered through ACF (co.aikar.commands) against a PaperCommandManager. Permission nodes are unprefixed (essentials.*) except two: the cooldown bypass (cooldown.bypass) and the command-blocking bypass (astralessentials.bypass.commandblock), both described under Cooldowns and Command gating below. Commands listed under unregistered-commands in config.yml are removed from the server entirely — see Installation — and /essentials reload (below) can be used to re-apply that list after editing it.

Gamemode

`/gamemode` (alias `/gm`)

Class-level permission essentials.gamemode gates the whole command (both variants below).

Invocation	Extra permission	Description
`/gamemode <mode>`	`essentials.gamemode.<mode>`	Change your own game mode.
`/gamemode <mode> <player>`	`essentials.gamemode.others` and `essentials.gamemode.others.<mode>`	Change another player's game mode.

<mode> is resolved by a custom GameMode context resolver and accepts, as literal (case-sensitive, not lower-cased) tokens: 0/s/survival, 1/c/creative, 2/a/adventure, 3/sp/spectator. Any other value throws an invalid-argument error before the command body runs. Tab-completion (@gamemodes) only offers the tokens for modes the sender holds essentials.gamemode.<mode> for — it is not filtered by the .others permissions for the target-player form.

A denied mode change (missing essentials.gamemode.<mode>/.others.<mode>) sends a hardcoded red/bold "You don't have permission to change to that game mode." message — this one is not sourced from messages.yml/EssentialsMessages, unlike the rest of the command's feedback.

Compact aliases

Alias	Mode
`/gms`, `/gm0`	Survival
`/gmc`, `/gm1`	Creative
`/gma`, `/gm2`	Adventure
`/gmsp`, `/gm3`	Spectator

All eight aliases are registered on one command class, gated the same way as /gamemode: class-level essentials.gamemode, plus essentials.gamemode.others (method-level) for the <player> form. The mode is inferred from the alias actually typed (getExecCommandLabel()), not from an argument.

Speed

Permission essentials.speed for the whole command.

Invocation	Description
`/speed [0-10]`	Set fly speed if you're currently flying, otherwise set walk speed. Defaults to `1`.
`/speed fly [0-10]`	Set fly speed explicitly.
`/speed walk [0-10]`	Set walk speed explicitly.

The integer argument (0–10, default 1) is divided by 10 to produce the Bukkit speed float (e.g. 5 → 0.5).

Heal & feed

Invocation	Permission	Cooldown key
`/heal`	`essentials.heal`	`heal`
`/heal <player>`	`essentials.heal` + `essentials.heal.others`	(none — no cooldown check on the others path)
`/feed`	`essentials.feed`	`feed`
`/feed <player>`	`essentials.feed` + `essentials.feed.others`	(none)

/heal fully heals (Attribute.MAX_HEALTH); /feed sets food level and saturation to 20. The <player> forms take a CommandSender, so they can be run from console, and only message the target and the sender — they do not consult the cooldown system at all.

Movement & world interaction

Command	Permission	Description
`/top`	`essentials.top`	Teleport to the highest safe block at your column. In the Nether, searches downward from `Y=128` for the first safe location instead of using the world's highest-block value. No-ops if you're already at/above the target or it isn't safe.
`/fire`	`essentials.fire`	Extinguish yourself (`setFireTicks(0)`) if currently on fire.
`/hat`	`essentials.hat`	Wear the item in your main hand as a helmet. Your previous helmet is returned to your inventory, or dropped at your feet if it doesn't fit. Fails on an empty main hand.
`/sit`	(none)	Sit on the slab or stair block you're looking at (within 5 blocks). Fires a synthetic `PlayerInteractEvent` first so protection plugins can deny it; spawns an invisible, non-colliding armor stand and mounts you on it, with a seat offset computed from stair facing/shape. Any previous sit for the same player is ejected and removed first.
`/candle`	`essentials.candle`	Toggle the lit state of the candle block you're looking at (within 5 blocks). Lighting fires a synthetic `BlockIgniteEvent`, extinguishing fires a synthetic `PlayerInteractEvent` — both must not be cancelled by another plugin for the toggle to apply.

Sudo

Invocation	Permission	Description
`/sudo <player> <command>`	`essentials.sudo`	Forces `<player>` to run `<command>` via `Player#performCommand`, using the target's own permissions. Takes a `CommandSender`, so it can be run from console.

Per-player time & weather

`/playertime` (alias `/ptime`)

Permission essentials.ptime for the whole command.

Invocation	Description
`/playertime <time>`	Set your personal time. If `time > 0`, calls `player.setPlayerTime(time, false)`; otherwise calls `player.resetPlayerTime()`. The raw `time` value is always written to your synced `PlayerTimeData`, even when it's `≤ 0`.
`/playertime reset`	Reset to server time (`player.resetPlayerTime()`) and store `0` in `PlayerTimeData`.

`/pweather`

Invocation	Permission	Description
`/pweather <storm\\|sun\\|clear\\|reset>`	`essentials.pweather`	Set your personal weather. Unlike the gamemode argument, this token is matched case-insensitively (`.toLowerCase()`). `storm` → downfall, `sun`/`clear` → clear, `reset` → back to server weather. An unrecognized token sends an invalid-weather-type message rather than erroring the command.

Both commands persist their state through SyncAPI in a PlayerTimeData record so it follows the player across servers — see AstralSync integration.

Inventory commands

Command	Aliases	Permission	Opens
`/craft`	`/workbench`, `/wb`, `/c`	`essentials.craft`	A virtual crafting table (`MenuType.CRAFTING`).
`/anvil`	—	`essentials.anvil`	AstralItems' custom anvil (`ItemsAPI.openAnvil`) — see Anvil.
`/stonecutter`	`/sc`	`essentials.stonecutter`	A virtual stonecutter (`MenuType.STONECUTTER`).
`/enderchest`	`/ec`	`essentials.enderchest`	Your own ender chest inventory.
`/trash`	`/poubelle`	(none)	A trash-bin GUI sized and titled from `trash-inventory` (`size`, `title`).

/trash has no permission requirement in source. Closing it with items still inside triggers a confirmation flow ([confirm-trash]/[refund-trash] actions) — see the Overview's trash-bin summary.

Item utilities

Command	Aliases	Subcommand	Permission	Cooldown key
`/repair`	`/fix`	(default), `hand`	`essentials.repair`	`repair`
`/repair all`		`all`	`essentials.repair` + `essentials.repair.all`	`repair-all`
`/furnace`	`/smelt`	(default)	`essentials.furnace`	`furnace`
`/furnace all`		`all`	`essentials.furnace` + `essentials.furnace.all`	`furnace-all`
`/condense`	—	(default)	`essentials.condense`	`condense`
`/condense all`		`all`	`essentials.condense` + `essentials.condense.all`	`condense-all`
`/xpbottle <amount> [level\\|exp] [bottles]`	`/bottlexp`	(default)	`essentials.xpbottle`	—
`/xpbottle all [amount]`		`all`	`essentials.xpbottle`	—
`/strip`	—	(default)	`essentials.strip`	`strip`
`/strip all`		`all`	`essentials.strip` + `essentials.strip.all`	`strip_all`
`/concrete`	—	(default)	`essentials.concrete`	`concrete`
`/concrete all`		`all`	`essentials.concrete` + `essentials.concrete.all`	`concrete-all`

/repair (hand or all) resets Damageable durability on items that have item meta and are not AstralItems custom items (ItemsAPI.isCustomItem); it's a no-op message (not a failure) if nothing in scope is repairable. /furnace and /condense look up the input material against the live Bukkit recipe iterator (/furnace) or the condensable-items config map (/condense) respectively; all variants batch across your whole inventory and deliver the output through AstralCore's MailboxService.giveOrAdd — added directly if there's room, otherwise queued to your mailbox with a chat notification — whereas the single-item variants place the result back in your main hand (/furnace) or hard-fail with an inventory-full message if it doesn't fit (/condense). /strip and /concrete both replace the held item(s) in place (stripped log/wood, or concrete powder → concrete) and don't touch the mailbox.

`/xpbottle` (alias `/bottlexp`)

/xpbottle <amount> [level|exp] [bottles]
/xpbottle all [amount]

type (level default, or exp, tab-completed via @expTypes) selects whether <amount> is interpreted as player levels (converted with ExperienceUtils.getExperienceFromTotalLevels) or raw XP points.
bottles (default 1) is how many bottles to fill; the plugin removes totalExp * bottles XP from the player up front and fails with a not-enough-experience message if that exceeds what they have.
/xpbottle all [amount] (default amount = 1) drains the player's entire current experience across amount bottles instead.
Both paths abort with an inventory-full message if the player has no completely empty slot — checked once up front, not per bottle produced.
Each bottle is built from the xp-bottle config entry and tagged with its XP value in a astralessentials:exp_bottle persistent-data key, consumed by ExperienceBottleListener on use.

Admin

Command	Permission	Description
`/essentials reload`	`essentials.command`	Reload `messages.yml`, `config.yml`, `cooldowns.yml`, `containers.yml`, and menus; re-applies `unregistered-commands`.

essentials.command is a class-level @CommandPermission, so it gates the entire /essentials base command. See Installation § Reloading configuration for the exact reload sequence and what it does not re-run.

Cooldowns

cooldowns.yml defines a Duration per throttled command, tracked per player through AstralCore's CooldownService under the key astralessentials:<command>. A zero/negative duration disables that command's cooldown. Players with the bare cooldown.bypass permission skip every cooldown check outright.

Key	Default (shipped `cooldowns.yml`)	Command
`feed`	`5m`	`/feed`
`heal`	`10m`	`/heal` (see note above — the value actually applied is `feed`'s)
`condense`	`15m`	`/condense`
`condense-all`	`30m`	`/condense all`
`furnace`	`1m`	`/furnace`
`furnace-all`	`5m`	`/furnace all`
`repair`	`20m`	`/repair`, `/repair hand`
`repair-all`	`1h`	`/repair all`
`strip`	(not present — see below)	`/strip`
`strip_all`	(not present — see below)	`/strip all`
`concrete`	`5m`	`/concrete`
`concrete-all`	`1h`	`/concrete all`

Being on cooldown sends COMMAND_ON_COOLDOWN with the remaining time (DurationParser.toHumanReadable) exposed as the time placeholder, and blocks the command.

Two source-level notes:

CooldownConfiguration has strip/stripAll fields (used by /strip), but the shipped cooldowns.yml resource only defines the ten keys above — strip and strip-all are absent from the default file.
/strip all's cooldown key is strip_all (underscore), while every other multi-word key in this plugin uses a hyphen (condense-all, furnace-all, repair-all, concrete-all) — so its CooldownService key is astralessentials:strip_all, not astralessentials:strip-all.

Two check patterns are used across these commands: /feed, /heal, /repair (hand), /furnace (single item), and /strip (single item) call checkCooldown, which checks and arms the cooldown in one call — the cooldown starts as soon as the pre-conditions pass. /repair all, /furnace all, /condense, /condense all, /strip all, /concrete, and /concrete all call isInCooldown up front and only call setInCooldown after the operation actually affected at least one item — no cooldown is applied if nothing happened.

Completions & context resolvers

Name	Kind	Used by	Behavior
`@gamemodes`	Async completion	`/gamemode <mode>`	Offers `survival`/`s`/`0` etc. only for modes the sender holds `essentials.gamemode.<mode>` for.
`GameMode` context resolver	Context	`/gamemode`	Parses the raw first argument into a `GameMode` per the token table above (case-sensitive), throwing an invalid-argument error otherwise.
`@weatherTypes`	Completion	`/pweather`	Static list: `clear`, `sun`, `storm`, `reset`.
`@expTypes`	Completion	`/xpbottle`	Static list: `level`, `exp`.
`@players`	Completion	`/gamemode <mode> <player>`, `/gms`… `/gm3 <player>`, `/heal <player>`, `/feed <player>`, `/sudo`	Standard ACF online-player completion (not registered by this plugin).
`@range:1-100`/`@range:1-64`	Completion	`/xpbottle <amount>` (1–100), `/xpbottle [bottles]` and `/xpbottle all [amount]` (1–64)	Standard ACF numeric-range completion.
`0\\|1\\|2\\|…\\|10`	Completion	`/speed [speed]`, `/speed fly [speed]`, `/speed walk [speed]`	A static pipe-delimited literal list, not `@range` — paired with a `@Range(from = 0, to = 10)` parameter validator that rejects out-of-range values ACF-side regardless of what was tab-completed.

Player-only vs console

Most commands on this page take a Player as their method's first argument, so they can only be run by a player in-game (ACF rejects console/command-block invocation before the method body runs). The exceptions that accept a CommandSender — and so can be run from console — are the <player>-targeting forms: /gamemode <mode> <player>, /gms… /gm3 <player>, /heal <player>, /feed <player>, /sudo, and /essentials reload.

EssentialsMessages declares a PLAYER_ONLY_COMMAND entry (player-only-command in messages.yml), but no command class in this plugin actually sends it — none of the Player-only commands catch and re-message a console invocation. In practice, a console/command-block attempt at a player-only command falls back to ACF's own built-in "player only" handling rather than this plugin's message.

Command gating

Beyond permissions, CommandListener can remove a command before it ever reaches ACF, keyed off MainConfiguration:

blocked-commands — command labels blocked everywhere; a match is also stripped from tab-completion and from PlayerCommandSendEvent's command list (so it doesn't even show as "known").
groups-blocked-commands — keyed by the server's own group (AstralPaperAPI.serverInformation().group(), e.g. resource), each entry listing a set of blocked command labels; a match sends COMMAND_DISABLED_IN_WORLD and cancels the command (unlike blocked-commands, it isn't hidden from tab-completion). Each entry's config schema also has a worlds field, but isCommandBlockedInGroup never reads it — blocking currently applies to the whole server group, not to specific worlds within it, despite the field's name. See World & Server Management § Command Restrictions for the full breakdown.
Players holding astralessentials.bypass.commandblock skip both checks (note the astralessentials. prefix — unlike every other permission on this page, which is unprefixed essentials.*).

Separately, the custom Nether/End portals (not chat commands, but gated the same way conceptually) check an AstralCore requirement list before teleporting — by default a [permission] world.nether/[permission] world.end node — with configurable deny-actions on failure. See World & Server Management § Custom Portals for the full configuration reference for both of these systems.

Permission summary

Node	Grants
`essentials.gamemode`	Base node for `/gamemode`, `/gm`, and the compact aliases.
`essentials.gamemode.survival`/`.creative`/`.adventure`/`.spectator`	Changing your own mode to that mode (self, on any gamemode command).
`essentials.gamemode.others`	`/gamemode <mode> <player>` and the compact `<player>` forms (method-level, on top of `essentials.gamemode`).
`essentials.gamemode.others.survival`/`.creative`/`.adventure`/`.spectator`	Changing another player's mode via `/gamemode <mode> <player>` only — the compact aliases check `essentials.gamemode.<mode>` instead.
`essentials.speed`	`/speed`, `/speed fly`, `/speed walk`.
`essentials.heal`	`/heal` (self).
`essentials.heal.others`	`/heal <player>`.
`essentials.feed`	`/feed` (self).
`essentials.feed.others`	`/feed <player>`.
`essentials.hat`	`/hat`.
`essentials.top`	`/top`.
`essentials.fire`	`/fire`.
`essentials.candle`	`/candle`.
`essentials.sudo`	`/sudo`.
`essentials.ptime`	`/playertime`, `/ptime`, and `reset`.
`essentials.pweather`	`/pweather`.
`essentials.craft`	`/craft`, `/workbench`, `/wb`, `/c`.
`essentials.anvil`	`/anvil`.
`essentials.enderchest`	`/enderchest`, `/ec`.
`essentials.stonecutter`	`/stonecutter`, `/sc`.
`essentials.repair`	`/repair`, `/repair hand`, `/fix`.
`essentials.repair.all`	`/repair all` (on top of `essentials.repair`).
`essentials.furnace`	`/furnace`, `/smelt`.
`essentials.furnace.all`	`/furnace all` (on top of `essentials.furnace`).
`essentials.condense`	`/condense`.
`essentials.condense.all`	`/condense all` (on top of `essentials.condense`).
`essentials.xpbottle`	`/xpbottle`, `/xpbottle all`, `/bottlexp`.
`essentials.strip`	`/strip`.
`essentials.strip.all`	`/strip all` (on top of `essentials.strip`).
`essentials.concrete`	`/concrete`.
`essentials.concrete.all`	`/concrete all` (on top of `essentials.concrete`).
`essentials.command`	`/essentials reload`.
`cooldown.bypass`	Skip every command cooldown (bare node, not `essentials.`-prefixed).
`astralessentials.bypass.commandblock`	Skip `blocked-commands`/`groups-blocked-commands` checks (`astralessentials.`-prefixed, not `essentials.`).

/sit and /trash//poubelle have no permission requirement in source.

Last modified: 25 July 2026