---
title: "Promotions"
slug: "promotions"
category: "Servers"
order: 5
description: "Log staff promotions, apply role changes, announce rank changes, and revoke promotions."
---

# 1 - Introduction

Promotions record staff rank grants. CADLY can apply a Discord role, show who issued the promotion, send a DM, and post a log message to your promotion channel.

Promotions are separate from [Infractions](/docs/infractions). Use promotions for positive rank movement and use infractions for warnings, strikes, suspensions, demotions, and terminations.

Promotions create an audit trail for rank movement. Instead of only adding a Discord role, CADLY records the reason, issuer, timestamp, and optional note so leadership can review why a rank was granted later.

Use the system even for small rank changes. Consistent records prevent confusion when staff transfer departments, return from LOA, or dispute rank history.

## 1.1 - Table of Contents

| Section | What it covers |
|---|---|
| [Issuing Promotions](#2---issuing-promotions) | Slash command and panel behavior |
| [History and Revocation](#3---history-and-revocation) | Filtering, details, and revoke behavior |
| [Settings](#4---settings--configuration) | Promotions settings reference |
| [Troubleshooting](#5---troubleshooting-common-issues) | Common permission and role issues |

## 1.2 - Links to Related Documents

- [Infractions](/docs/infractions)
- [Server Settings](/docs/server-settings)

# 2 - Issuing Promotions

Use **/promotion issue** with `user`, `role`, `reason`, and optional `note`. CADLY checks the issuer's promotion permission and Discord role hierarchy before applying role changes.

The panel Promotions page also supports issuing promotions for users visible to the server. Commands and panel actions create the same promotion record.

The `role` field is the Discord role being granted, so your rank structure should be represented by Discord roles. If your community uses multiple role layers, promote only the role that represents the rank change and leave department, certification, or specialty roles to their own process.

The optional note is best for internal context such as vote result, training class, or command approval. It should not replace the public reason.

```cadly-mock
type: record
title: Promotion record
meta: Promotions > Rank history
status: Applied
items:
- User | @RiversideUnit
- Role Granted | @Senior Moderator
- Reason | Completed field training
- Note | Approved by command staff
```

## 2.1 - Promotion Fields

| Field | Purpose |
|---|---|
| User | Discord member receiving the promotion. |
| Role | Discord role to add. |
| Reason | Required reason shown in history and messages. |
| Note | Optional internal note. |

## 2.2 - Hierarchy Protection

CADLY refuses promotions when the target has an equal or higher role than the actor. If the bot cannot apply a role because of hierarchy, the **Hierarchy Block Policy** decides whether to fail or let you confirm a partial action.

# 3 - History and Revocation

Use **/promotion list** to list your own promotions or another user's promotions when you have Manage Promotions permission. The panel shows a paginated history and supports filtering by user.

Use **/promotion revoke** with `promotion_id` and optional `reason` to mark a promotion revoked. Depending on settings, CADLY can leave roles untouched, remove the issued role, or restore a previous rank when one is available.

Revocation is an audit action, not a delete. The original promotion stays in history and is marked revoked. This is important when a promotion was made in error or a rank change is reversed after review.

If you want demotions to appear in discipline history, use [Infractions](/docs/infractions) with the demotion type. Promotion revoke is mainly for undoing the promotion record itself.

# 4 - Settings / Configuration

## 4.1 - Promotions Module

### Enable Promotions
Turns the promotions module on or off.
**Default:** on | **Requires:** none

### Promotions Channel
Channel where promotion logs are sent.
**Default:** none | **Requires:** none

### Revoke Behavior
Controls role changes when a promotion is revoked: do nothing, remove the issued rank, or restore the previous rank when available.
**Default:** none | **Requires:** none

Use `none` when leadership wants to handle role corrections manually. Use remove issued rank when promotions are simple one-role grants. Use restore previous rank only if your workflow reliably tracks previous rank information.

### Hierarchy Block Policy
Controls what happens when some role changes cannot be applied: fail the action or allow confirmation for partial changes.
**Default:** confirm partial | **Requires:** none

## 4.2 - Message Templates

### Customize Promotion DM
DM sent to the promoted user.
**Default:** CADLY default promotion DM | **Requires:** none

### Customize Promotion Message
Message sent to the promotions channel.
**Default:** CADLY default promotion log | **Requires:** none

### Customize Promotion Revoke DM
DM sent when a promotion is revoked.
**Default:** CADLY default revoke DM | **Requires:** none

### Customize Promotion Revoke Log Message
Log message sent or edited when a promotion is revoked.
**Default:** CADLY default revoke log | **Requires:** none

# 5 - Troubleshooting Common Issues

## 5.1 - Promotion Cannot Apply the Role

Move the CADLY bot role above the target rank role and ensure the issuer outranks the target member.

## 5.2 - No Promotion Log Appears

Set Promotions Channel and confirm the bot can send messages in that channel.

## 5.3 - Revoke Did Not Remove a Role

Check Revoke Behavior. The default is no role change.

# 6 - Getting Support and Resources

If you need help, several resources are available:
- [CADLY Documentation](/docs): Detailed reference for all features.
- [CADLY Support Server](https://discord.gg/cadly): Join for **fast help** from the team.
- [CADLY Email Support](mailto:admin@cadly.me): Reach out **via email** for direct support.