Documentation

Prerequisites

Installation

pip install flaken

That's it. Verify it worked:

flaken --help

Full Bot Setup

Create a file called bot.py:

import os
import discord
from discord.ext import commands
from flakes.leveling import LevelingSystem

intents = discord.Intents.default()
intents.message_content = True
intents.members = True

bot = commands.Bot(command_prefix="!", intents=intents)

async def main():
    async with bot:
        await bot.add_cog(LevelingSystem(bot))
        await bot.start(os.environ["DISCORD_BOT_TOKEN"])

import asyncio
asyncio.run(main())

Intent requirements by flake:

message_content — required for Leveling XP tracking and all prefix commands.
members — required for Welcome System (member join events) and Moderation (member lookups).
Enable both in the Developer Portal under Bot → Privileged Gateway Intents.

Command Styles

Flakes support different command styles. Choose per-flake when installing:

flaken add flaken/leveling                 # hybrid (default)
flaken add flaken/moderation --style prefix
flaken add flaken/welcome -s appcmd
Flag
Style
Commands
When to use
-s hybrid
hybrid
!rank and /rank
You want both prefix and slash commands
-s prefix
prefix
!kick only
You want fast keyboard commands, no slash registration
-s appcmd
appcmd
/setwelcome only
Clean Discord UI, discoverable commands

Prefix commands use ! by default. Change it when creating your bot:

bot = commands.Bot(command_prefix="?", intents=intents)

CLI Reference

flaken init                  Initialize flaken in the current project
flaken search <query>        Search the registry for flakes
flaken add <id>              Install a flake (add --force to overwrite)
flaken add <id> -s prefix   Install with prefix-only commands
flaken remove <id>          Remove an installed flake
flaken list                  List installed flakes
flaken info <id>            Show flake details, config, and dependencies
flaken update                Check for and install newer versions of all flakes

When you run flaken add, the flake is downloaded to flakes/<name>/ in your project. Import it like any other Python module:

from flakes.leveling import LevelingSystem

Flake Reference

Leveling System

hybrid — XP tracking with rank cards and leaderboards

from flakes.leveling import LevelingSystem

bot.add_cog(LevelingSystem(
    bot,
    xp_per_message=15,         # XP awarded per message (default: 15)
    xp_cooldown=60,           # Cooldown in seconds between XP grants (default: 60)
    levels={"1": 0, "5": 100, "10": 500},  # Level thresholds (default)
    data_path="leveling_data.json",  # Where XP data is stored (default)
))

Commands: !rank [@user] / /rank — !leaderboard / /leaderboard

Events: Tracks every message, awards XP on cooldown, announces level-ups in chat.

Required pip deps: aiofiles>=23.0.0

Moderation Suite

hybrid — Kick, ban, warn, purge, and timeout

from flakes.moderation import ModerationSuite

bot.add_cog(ModerationSuite(
    bot,
    warn_data_path="warns.json",  # Where warnings are stored (default)
))

Commands: !kick <@user> [reason] / /kick — !ban <@user> [reason] / /ban — !purge <amount> / /purge — !warn <@user> [reason] / /warn — !warns <@user> / /warns — !timeout <@user> <minutes> [reason] / /timeout

Permissions: Each command checks that you have the required mod permission. The bot also needs the matching permission in the server.

Welcome System

hybrid — Automatic welcome messages and role assignment

from flakes.welcome import WelcomeSystem

bot.add_cog(WelcomeSystem(
    bot,
    welcome_channel_name="welcome",  # Channel to send welcome messages (default: welcome)
    welcome_message="Welcome {member}!",  # Use {member} for the mention (default)
    auto_role_name="Member",  # Role to assign on join (leave blank to disable)
))

Commands: !setwelcome <#channel> / /setwelcome — !setwelcomemsg <text> / /setwelcomemsg

Events: Listens for new members joining the server.

Reaction Roles

hybrid — Self-assign roles by reacting to a message

from flakes.reaction_roles import ReactionRoles

bot.add_cog(ReactionRoles(
    bot,
    data_path="reaction_roles.json",
))

Commands: !setupreaction <msg_id> <emoji> <@role> / /setupreaction — !removereaction <msg_id> <emoji> / /removereaction

Events: Listens for reaction add/remove and assigns/unassigns roles automatically.

Ticket System

hybrid — Support tickets via buttons and threads

from flakes.tickets import TicketSystem

bot.add_cog(TicketSystem(
    bot,
    category_name="tickets",  # Category for ticket channels (default)
    staff_role_name="Staff",  # Role that can manage tickets (default)
))

Commands: !ticketpanel / /ticketpanel — !close / /close

Events: Creates ticket channels with proper permissions when users click the button.

Troubleshooting

"PrivilegedIntentsRequired" error

Go to the Discord Developer Portal, select your bot application, click Bot, scroll to Privileged Gateway Intents, and enable MESSAGE CONTENT INTENT and SERVER MEMBERS INTENT.

"This interaction failed" on slash commands

Slash commands sync to Discord on bot startup. Wait a few seconds after the bot comes online, then type / again. If they still don't appear, restart the bot.

Commands send duplicate responses

This usually means you have two bot instances running. Check for other Python processes and kill them:

taskkill /F /IM python.exe   # Windows
pkill -f bot.py              # Linux/Mac

Then start your bot fresh.

"X permission" errors on commands

Moderation commands check your permissions first, then the bot's. Make sure both you and the bot have the required role permissions in the Discord server.

Leveling XP isn't tracking

The XP system requires the message_content intent enabled (see above). It also has a 60-second cooldown per user by default, so send a few messages spread apart.