Commands
QBCore ships with a flexible command system that supports permissions, argument definitions, and automatic chat suggestions.
Use the QBCore.Commands API to register new commands, refresh suggestions, and manage permissions for your staff.
Registering Commands
QBCore.Commands.Add(name, help, arguments, argsrequired, callback, permission)
Registers a chat command that executes the supplied callback on the server.
Parameters:
name(string): Command name (without the/prefix)help(string): Description displayed in the chat suggestions listarguments(table): Array of argument definitions ({name = 'id', help = 'Player ID'})argsrequired(boolean): Require all arguments before executing the callbackcallback(function): Function executed when the command runs (receivessourceandargs)permission(string | table, optional): Required permission level ('user','mod','admin','god') or list of levels
Example:
QBCore.Commands.Add('giveitem', 'Give an item to a player', {
{name = 'id', help = 'Player ID'},
{name = 'item', help = 'Item name'},
{name = 'amount', help = 'Quantity to give'},
}, true, function(source, args)
local targetId = tonumber(args[1])
local itemName = args[2]
local amount = tonumber(args[3]) or 1
local Target = QBCore.Functions.GetPlayer(targetId)
if not Target then
QBCore.Functions.Notify(source, 'Player not online', 'error')
return
end
Target.Functions.AddItem(itemName, amount)
TriggerClientEvent('inventory:client:ItemBox', targetId, QBCore.Shared.Items[itemName], 'add')
end, 'admin')Command Arguments
Argument definitions control the help text and whether inputs are optional.
{
{name = 'id', help = 'Target player ID'},
{name = 'amount', help = 'Money amount', optional = true}
}- Set
optional = trueto allow the command to run without that argument. - Use descriptive
helptext so players know what to input. - Arguments are delivered to the callback in the same order.
Managing Commands
QBCore.Commands.Remove(name)
Removes a previously registered command.
Example:
QBCore.Commands.Remove('giveitem')QBCore.Commands.Refresh(source?)
Rebuilds the command suggestion list for the specified player (or everyone when source is omitted).
Parameters:
source(number, optional): Player ID to refresh. If nil, all connected players are refreshed.
Example:
-- Refresh a single player after changing permissions
QBCore.Commands.Refresh(src)
-- Refresh everyone after adding a batch of commands
QBCore.Commands.Refresh()Accessing the Command List
All registered commands are stored in QBCore.Commands.List, which can be useful for debugging or building custom suggestion systems.
Example:
for name, command in pairs(QBCore.Commands.List) do
print(('/%s - %s'):format(name, command.help))
endPermission System
Permissions determine who can run restricted commands. By default the hierarchy is:
user– Standard playersmod– Junior staff helpersadmin– Administratorsgod– Owners / super admins
To assign permissions, configure QBConfig.Server.PermissionList in server/config.lua or adjust the ACL in your admin resource. Combine permission strings in the permission parameter to allow multiple roles:
QBCore.Commands.Add('dv', 'Delete the closest vehicle', {}, false, function(source)
TriggerClientEvent('QBCore:Client:DeleteVehicle', source)
end, {'admin', 'god'})You can also perform manual checks inside a command using QBCore.Functions.HasPermission(source, 'admin') for finer control.
Built-in Commands
QBCore registers a core set of admin and utility commands. Common examples include:
| Command | Permission | Description |
|---|---|---|
/dv | admin | Delete the closest vehicle |
/setjob | admin | Set a player’s job and grade |
/setgang | admin | Set a player’s gang and grade |
/tp | admin | Teleport to coordinates or a player |
/giveitem | admin | Give an item to a player |
/setperm | god | Adjust a player’s permission level |
/ban | god | Ban a player from the server |
Refer to the qb-core/server/commands.lua file for the full list of built-ins and their implementations.
Related Documentation
- Server Functions - Server-side helper functions
- Client Functions - Client helper utilities
- Server Events - Server event reference
- Client Events - Client event reference
- Permissions Guide - Configuring permission lists for your staff