Commands

HeadDB commands use either root alias:

/hdb
/headdb

The in-game help output is permission-aware:

/hdb help

Syntax

Syntax	Meaning
(alias)	Optional command alias.
<value>	Required argument.
[value]	Optional argument.

General and GUI

Command	Alias	Permission	Description
/hdb	/headdb	headdb.open, headdb.gui.main	Opens the main GUI when gui.open-main-command is enabled.
/hdb help	/hdb h	headdb.command.help	Shows available commands.
/hdb version	/hdb v	headdb.command.version	Shows version, build, and update information.
/hdb open [category] [player]	/hdb o	headdb.command.open	Opens the main GUI or a category for yourself or another player.

Opening a GUI for another player also requires headdb.command.open.others.

Heads and player heads

Command	Alias	Permission	Description
/hdb info [id]	/hdb i	headdb.command.info	Shows information for a head ID or compatible held head.
/hdb give <id> [player] [amount]	/hdb g	headdb.command.give	Gives a remote or typed HeadDB head.
/hdb player <name-or-uuid> [target] [amount]	/hdb p	headdb.command.player	Gives a player head.
/hdb random [amount] [category] [player]	/hdb rnd	headdb.command.give	Gives one or more random heads.

Giving heads to another player requires the corresponding .others permission.

Examples:

/hdb info 123
/hdb give 123
/hdb give 123 Steve 4
/hdb player Notch
/hdb random 3 blocks

Search and browse

Command	Alias	Permission	Description
/hdb search <query>	/hdb s	headdb.command.search	Searches by text and opens search results for players.
/hdb search text <query>	—	headdb.command.search	Explicit text search.
/hdb search tag <tag>	—	headdb.command.search	Filters by tag.
/hdb search category <category>	—	headdb.command.search	Filters by category.
/hdb search collection <collection>	—	headdb.command.search	Filters by collection.
/hdb search head <id>	—	headdb.command.search	Searches for one typed head ID.
/hdb categories [page]	/hdb cat	headdb.search	Lists available categories.
/hdb tags [query] [page]	/hdb t	headdb.search	Lists or searches tags.
/hdb collections [query] [page]	/hdb col	headdb.search	Lists or searches collections.

Search subcommands support applicable options for sort, direction, page, and result limit.

Custom Heads

The command group remains /hdb custom; the public feature name is Custom Heads.

Command	Permission	Description
/hdb custom list [page]	headdb.command.custom.list	Lists local Custom Heads.
/hdb custom info <id>	headdb.command.custom.info	Shows Custom Head information.
/hdb custom create <id> <texture> [name]	headdb.command.custom.create	Creates a Custom Head from a texture.
/hdb custom createheld <id> [name]	headdb.command.custom.create	Creates a Custom Head from the held head.
/hdb custom give <id> [player] [amount]	headdb.command.custom.give	Gives a Custom Head.
/hdb custom delete <id>	headdb.command.custom.delete	Deletes a Custom Head.
/hdb custom rename <id> <name>	headdb.command.custom.rename	Renames a Custom Head.

Tags and collections administration

Command	Permission	Description
/hdb tags create <id> <name>	headdb.command.tags.create	Creates a local custom tag.
/hdb tags delete <id>	headdb.command.tags.delete	Deletes a local custom tag.
/hdb collections create <id> <name>	headdb.command.collections.create	Creates a local custom collection.
/hdb collections delete <id>	headdb.command.collections.delete	Deletes a local custom collection.

Administration and database

Command	Alias	Permission	Description
/hdb edit [id]	—	headdb.command.edit	Opens the metadata editor for a specified or held remote head.
/hdb status	/hdb st	headdb.command.status	Shows concise database state and counts.
/hdb debug	/hdb d	headdb.command.debug	Shows concise runtime diagnostics.
/hdb report	/hdb rpt	headdb.command.report	Generates a full copyable support report.
/hdb verify	—	headdb.command.verify	Verifies remote artifacts without replacing the active database.
/hdb refresh	/hdb ref	headdb.command.refresh	Checks and activates the latest remote database.
/hdb reload	—	headdb.command.reload	Reloads configuration and runtime services.
/hdb update	—	headdb.admin.update	Checks for and downloads the newest allowed plugin release.
/hdb itemcache clear	/hdb ic clear	headdb.command.itemcache	Clears generated head-item cache entries.

For normal administration, prefer the GUI editor and Admin Mode over low-level command workflows.