# QBCore commands

This page is pinned to
[`server/commands.lua`](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/commands.lua).

![Server command ACE permission and handler checks](/diagrams/permissions.svg)

*Conceptual diagram; verify the behavior against your installed resource version.*

## Register a command

```lua
QBCore.Commands.Add(name, help, arguments, argsrequired, callback, permission, ...)
```

Additional accepted permissions are extra arguments, for example `..., 'admin', 'god')`.

| Parameter | Type | Meaning |
| --- | --- | --- |
| `name` | string | Command name, stored lowercased |
| `help` | string | Description shown in the command list |
| `arguments` | table | Array of `{ name = ..., help = ... }` entries |
| `argsrequired` | boolean | When true, refuses with a chat error if fewer args than `#arguments` are supplied |
| `callback` | function | Called as `callback(source, args, rawCommand)` |
| `permission` | string | Defaults to `'user'` |
| `...` | strings | Additional permission levels that may also run it |

This is a server-side wrapper around `RegisterCommand`. What it adds at the pinned commit:

- **Ace permissions.** For any permission other than `user` or `god`, it runs
  `add_ace qbcore.<permission> command.<name> allow` and registers the command as restricted. `god`
  is skipped because it is allowed everything, and `user` is skipped because it maps to
  `builtin.everyone`.
- **A cancellable pre-execution event.** It fires `QBCore:Server:PreCommandExecution` with the
  source, name, args, and raw command, and aborts if a handler cancels it. That is the hook for
  audit logging or a per-command lockout.
- **An argument count check** driven by `argsrequired`.
- **A registry** at `QBCore.Commands.List`, keyed by the lowercased name.

Because `permission` defaults to `'user'`, omitting it produces an unrestricted command.

```lua
QBCore.Commands.Add('routecount', 'Show active delivery routes', {}, false, function(source)
    QBCore.Functions.Notify(source, ('Active routes: %d'):format(countRoutes()), 'primary')
end, 'admin', 'god')
```

Argument definitions contain `name` and `help`. Use `optional = true` only when the callback handles
the missing value. Parse numbers and validate player IDs inside the callback.

## Refresh suggestions

`QBCore.Commands.Refresh(source)` rebuilds chat suggestions for one connected player. It requires a
real player source; it is not a broadcast API. The current core has no `QBCore.Commands.Remove`.

## Permissions

Current permission names are configured in `QBCore.Config.Server.Permissions` in the root
`config.lua` and backed by ACE/principal rules in `server.cfg`. Check permissions again inside any
command that changes privileged state.

Current core commands include `tp`, `tpm`, `togglepvp`, `addpermission`, `removepermission`,
`openserver`, `closeserver`, `car`, `dv`, `dvall`, `dvp`, `dvo`, `givemoney`, `setmoney`, `job`,
`setjob`, `gang`, `setgang`, `ooc`, and `me`. Inventory resources and admin resources can register
additional commands; do not assume `/giveitem` or `/ban` comes from current `qb-core`.
