Configure a Discord guild

This program configures a Discord guild based on a given configuration.

See configs for an example configuration.

Features

Features:

• Enable 'Community Server' features
• Configure system channels
• Update roles
  • Add missing roles
  • Update colors
  • Update 'hoist' flag
  • Update 'mentionable' flag
  • Update role permissions
• Update categories, text channels, and forums
  • Add missing categories, text channels, and forums
  • Update positions
  • Add missing forum tags
  • Update the 'mandatory/optional' state of forum tags
  • Update category, text channel, and forum permission overwrites
• Update category and channel permission overwrites
• Update channel's default messages

Deliberate omissions:

• Delete roles
• Delete categories
• Delete channels
• Delete forum tags
• Delete human-authored messages

All operations are idempotent. Applying the same configuration twice will perform no changes.

Planned features

• Guild configurator: Configure role order. Currently, this requires manual intervention.
• Guild configurator CLI: Read configuration from a file. Currently, the EP2025 configuration is hardcoded.
• New program: Export the configuration of an existing guild.

Usage instructions

Discord setup

Create a Discord bot with the privileges for receiving GUILD_MEMBER events on the target guild.

Command-line usage

• Set the environment variable BOT_TOKEN to the bot's access token.
• Install this package, e.g., with pip install . or uv sync.
• Run discord-guild-configurator --guild-id <GUILD_ID> --config-file <JSON_FILE>.
  • You can use --verbose or --debug to receive more detailed output.

Programmatic usage

# Option 1: Create guild configuration programmatically
from discord_guild_configurator.configurator import GuildConfigurator
from discord_guild_configurator.models import GuildConfig

GUILD_CONFIG = GuildConfig(...)

# Option 2: Load guild configuration from a JSON file
import json
from pathlib import Path

from discord_guild_configurator.models import GuildConfig

config_file = Path("guild_config.json")
config_file_content = config_file.read_text(encoding="UTF-8")
GUILD_CONFIG = GuildConfig.model_validate_json(config_file_content)

# Apply the configuration
from discord_guild_configurator.bot import GuildConfigurationBot, run_bot

BOT_TOKEN = "YOUR_TOKEN"
GUILD_ID = 123456789

async def configure_guild(guild) -> None:
    configurator = GuildConfigurator(guild)
    await configurator.apply_configuration(GUILD_CONFIG)

bot = GuildConfigurationBot(GUILD_ID, action=configure_guild)
run_bot(bot, BOT_TOKEN)

Development

This project uses the following tools:

• uv for Python project and dependency management
• ruff for Python code linting and formatting
• ty for Python type checking
• prek for running code checks on each commit and in CI
• GitHub Actions for continuous integration