> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cc-scripts.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin commands

> Console + ACE-gated commands for granting XP and triggering test runs.

`cc_heistcontracts` ships one console command, `/heist:grantxp`, ACE-gated. Everything else administrative is direct SQL or `cc_heistcontracts` restarts.

## `/heist:grantxp <alias> <amount>`

Grant XP to a profile by alias. Handles level-ups and pushes a fresh profile sync to the recipient if they're online.

```
/heist:grantxp ghost_42 5000
```

|                       |                                                                                                                                                                                                    |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Restricted**        | Yes — `restricted = true` on the registration.                                                                                                                                                     |
| **Allowed callers**   | Console (source 0), or in-game admins with the `command.heist:grantxp` ACE permission, or the `admin` ace.                                                                                         |
| **Online recipient**  | Mutates the cached profile, marks it dirty (next 30s flush persists it), and immediately calls `_G.HeistSync.SendProfile(src)` so the dashboard updates without waiting for the next sync request. |
| **Offline recipient** | Resolves alias → `citizenid` via a single `SELECT`, computes the new level/XP, and updates the row directly. Doesn't pollute the in-memory cache (no owner src).                                   |

### ACE setup

Either grant the dedicated permission:

```
add_ace group.admin command.heist:grantxp allow
```

Or use the catch-all `admin` ace. Built-in superadmins are usually in `group.admin` already.

### Output

```
[heist:grantxp] ghost_42 +5000 XP → level 8, xp 12450 (leveled up from 7)
```

If the alias doesn't exist:

```
[heist:grantxp] failed: not_found
```

Other failure codes: `invalid_amount` (zero/negative), `db` (UPDATE didn't affect any rows).

## Debug logging

`config.debug = true` in `shared/config.lua` toggles `[DEBUG]` lines from `utils.dprint`. Default is **off** in the shipped config — flip it on locally when investigating. Useful lines you'll see:

* `[DEBUG] listing added: <contractId> (N/max)` — every time the drip thread successfully adds a listing.
* `[DEBUG] listings expired: N removed, M remain` — every expiry sweep that finds something to cull.
* `[DEBUG] entry_point error for <id>: <msg>` — when a contract's entry point throws on Start. The active-slot mark is rolled back when this happens.
* `[DEBUG] reset error for <id>: <msg>` — when a contract's cooldown `reset` callback throws.
* `[DEBUG] Profile.GetBySrc: no citizenid for src <n>` — citizenid lookup failed (usually means the player isn't fully loaded into the core yet).

Server prints (not gated by `debug`) also include:

* `[cc_heistcontracts] CancelHeist threw for <resource>: <msg>` — a heist resource's `CancelHeist` export raised an exception during a give-up flow.

With `config.debug = false` (the shipped default) you only see server prints on actual failures.