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 list
• arguments (table): Array of argument definitions ({name = 'id', help = 'Player ID'})
• argsrequired (boolean): Require all arguments before executing the callback
• callback (function): Function executed when the command runs (receives source and args)
• 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 = true to allow the command to run without that argument.
• Use descriptive help text 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))
end

Permission System

Permissions determine who can run restricted commands. By default the hierarchy is:

• user – Standard players
• mod – Junior staff helpers
• admin – Administrators
• god – 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:

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