fluxer-py-template

A template repository for quickly bootstrapping a fluxer.py bot. Clone it, configure your token, and have a working bot running in minutes.

For support or more info, join the fluxer.py community!

Features

• Auto-loads cogs from the cogs/ directory
• Configurable command prefix and log level via environment variables
• Docker support with a secure non-root image
• Linting via GitHub Actions pre-configured: ruff for formatting/linting, pyright for type checking, uv for dependency management

Included example cogs

Cog	Command	Description
cogs/ping.py	!ping	Replies with Pong!
cogs/admin.py	!kick <user_id>	Kicks a user (requires KICK_MEMBERS permission)

Getting started

1. Use this template

Click "Use this template" on GitHub to create your own repository, then clone it:

git clone https://github.com/your-username/your-bot-name
cd your-bot-name

2. Configure environment variables

Copy the example env file and fill in your bot token:

cp example.env .env

Edit .env:

PREFIX=!
FLUXER_TOKEN=your_token_here
LOG_LEVEL=INFO

3. Run the bot

With Docker (recommended):

make build
make run

Locally with uv:

uv run main.py

Adding a new cog

Create a new file in cogs/, e.g. cogs/greet.py:

import fluxer
from fluxer import Cog


class Greet(Cog):
    def __init__(self, bot: fluxer.Bot):
        super().__init__(bot)

    @Cog.command()
    async def hello(self, ctx: fluxer.Message):
        """Says hello!"""
        await ctx.reply(f"Hello, {ctx.author.display_name}!")


async def setup(bot: fluxer.Bot):
    await bot.add_cog(Greet(bot))

The cog is picked up automatically on next startup — no registration required.

Make targets

Target	Description
make build	Build the Docker image
make run	Run the bot in Docker
make format	Format code with ruff
make lint	Lint with ruff and pyright

Requirements

• Python 3.13+
• uv for local development
• Docker (optional, for containerised deployment)