Commands and permissions

The primary command is /headdb. /hdb, /headdatabase, and /headmenu are equivalent aliases. Tab completion only shows commands and categories the sender is allowed to use.

Everyday commands

Command	Purpose	Permission
/hdb	Open the main menu.	headdb.command.open
/hdb open [category]	Open the main menu or a specific category.	headdb.command.open plus category access
/hdb search <query and filters>	Search and open the results menu.	headdb.command.search
/hdb submit	Show a clickable link to the authenticated head submission page.	headdb.command.submit
/hdb give [amount] <head>	Give yourself a head by name, id:<id>, or texture hash.	headdb.command.give
/hdb give <player> <amount> <head>	Give a head by name, id:<id>, or texture hash.	headdb.command.give
/hdb info	Show the HeadDB, Java, and server versions.	headdb.command.info
/hdb sounds	Toggle interface sounds for the current player.	headdb.command.sounds
/hdb inspect [head]	Inspect a held or identified catalog head and open its web page.	headdb.command.inspect
/hdb recent	Browse the entries with the most recently assigned IDs.	headdb.command.recent
/hdb language [language]	List or choose a personal message language.	headdb.command.language
/hdb status	Show catalog revision, source, size, and synchronization health.	headdb.command.status
/hdb sync	Synchronize the managed catalog now.	headdb.command.sync
/hdb reload	Reload runtime messages, menus, prices, links, sounds, and categories.	headdb.command.reload

Opening menus, searching, submitting, and toggling sounds require a player. The give and info commands can also be run from the console.

After an in-game search completes, HeadDB can show a clickable link to the same search on headdb.net. The browser catalog provides richer filtering, 3D head previews, and ready-to-copy give commands. The hint can be disabled without disabling /hdb search; see Plugin configuration.

Browse and take heads

Run /hdb and choose a category. In the default modern interface:

• the attack/left-click action takes a head when economy support is disabled;
• the use/right-click action toggles the head in the player's favorites;
• when economy support is enabled, the attack action opens the purchase menu.

Players only see categories for which they have permission. Favorites, local player heads, and custom categories have their own permission nodes.

Search syntax

A plain query matches part of a head name:

/hdb search dragon

Filters are case-insensitive and use complete category or tag names:

/hdb search category:Alphabet rune
/hdb search tags:rune
/hdb search ids:103838,103839

By default every supplied filter must match. Add --any to match when any filter or name term succeeds:

/hdb search --any Flag tags:rune

Comma-separated values are accepted by tags: and ids:. Quote category or tag values containing spaces: category:"Food & Drinks".

Give heads directly

Use a stable HeadDB ID when automating commands:

/hdb give Steve 1 id:103838

A complete head name or Mojang texture hash is also accepted:

/hdb give Steve 64 Oak Log
/hdb give Steve 1 a0825e771a1c66f08708003d57a04a147e2774469459d9fb3041f549865f1fd3

Players can omit their own name and the amount defaults to one:

/hdb give id:103838
/hdb give 64 Oak Log

The amount must be between 1 and maxBuyAmount from config.yml. Items that do not fit in the target inventory are dropped at the player's location.

Permission setup

Most command and category permissions default to operators. The sounds command defaults to all players.

Permission	Grants
headdb.admin	Every HeadDB command, category, and update notification.
headdb.command.open	Main and category menus.
headdb.command.search	Catalog search.
headdb.command.give	Direct give command.
headdb.command.info	Version and server information.
headdb.command.sounds	Personal sound toggle.
headdb.command.submit	Website submission link.
headdb.command.status	Catalog health and revision.
headdb.command.sync	Immediate catalog synchronization.
headdb.command.reload	Runtime configuration reload.
headdb.command.inspect	Held or identified head inspection.
headdb.command.recent	Recently assigned IDs.
headdb.command.language	Personal message language.
headdb.update.notify	New-release notifications.
headdb.category.*	Every database category plus local, custom, and favorites.
headdb.category.<category_id>	One database or custom category.
headdb.category.local	Heads generated from known server players.
headdb.category.custom	The custom-category menu.
headdb.category.favorites	The favorites menu.

Category permission IDs are lowercase, with spaces and symbols normalized to underscores. For example, Food & Drinks uses headdb.category.food_drinks.

A typical LuckPerms setup is:

/lp group default permission set headdb.command.open true
/lp group default permission set headdb.command.search true
/lp group default permission set headdb.command.sounds true
/lp group default permission set headdb.category.* true

To allow every category except local player heads, explicitly deny the more specific node:

/lp group default permission set headdb.category.local false