Aire

Aire is a Discord bot made by Stormzady (150x2). It has fun commands (8ball, coinflip, dog, joke, ship, games, Question of the Day), server tools (parrot, ads, pins, bans) and a way to control FrogBot in the Minecraft server (e!mc). Maintained by Bingo.

Setup

1. Install uv and Python 3.14.
2. Make a .env file next to main.py with your bot token (see main.py for the variable name). Never commit it. It is listed in .gitignore.
3. Run it:

uv run main.py

It runs as a systemd service on the Pi (aire.service). Restart it with sudo systemctl restart aire.

Commands

The prefix is e! (or mention the bot). Many commands also work as slash commands. Use e!help for the full list.

Some commands are owner-only (owners are set in owner_ids in main.py). Some are Belugat's Safe Space only (BSS_IDS).

Files

• main.py: starts the bot, events (on_ready, on_message, errors)
• severn.py: Severn (Core), config, the bot object and helpers shared by everything
• cogs/: the commands, one file per area (ads, presence, settings, fun, utility, minecraft, bss). Importing a file registers its commands, so add a new file there and import it in main.py
• errors.py: custom errors
• config.toml: settings (owners, BSS server IDs, rate limit, health port, backup count). No secrets in it
• db.py: the database (SQLite, aire.db, not committed): bans, parrot, QOTD, daily streaks, ads. The old *.json files were imported on first run and are only kept as a backup
• aire.log: log of commands and errors (rotates, not committed)

Logging

Every command run is logged to aire.log and the console with the user, server and message. Errors are logged as warnings.

Errors

If a command crashes, the user gets a short message with an error id and the full traceback goes to aire.log under that id. Nearly every command works as both e!command and /command (only exec is prefix-only on purpose).

Owner tools

• e!reload [module|all]: reload a command module without restarting (old code is kept if the new code fails)
• e!logs [lines] [errors]: show the last lines of aire.log
• e!backup: back up the database now. A backup is also made daily at 04:00 UTC into backups/ (the newest backup_keep are kept)
• e!stats: uptime, latency, servers, most used commands and errors

Health check

curl http://127.0.0.1:8089/health returns JSON: 200 when Aire is connected and the database answers, 503 otherwise. It only listens on localhost.

Rate limit

Each user can run at most 6 commands per 10 seconds (change in config.toml). Owners are exempt.

Server setup and Question of the Day

• /setup (needs Manage Server) is a step-by-step wizard: QoTD channel and daily AI question, parrot, welcome messages, then a summary.
• With the daily AI question on, each server picks the hour and time zone in /setup (default 12:00 UTC, qotd_hour_utc in config.toml). Aire checks every hour. /qotdnow posts one right away.
• Questions are written by Claude Haiku. Aire uses ANTHROPIC_API_KEY from .env if there is one (never commit it); otherwise it runs the Claude Code CLI (claude -p, no tools, nothing saved) as the user set in config.toml. If both fail, it uses a built-in list of questions.
• Welcome messages support {user}, {server} and {count}.

Community features (all off by default, per server)

Turn them on in /setup or with /config (needs Manage Server). /config toggle <feature> on|off, /config channel <feature> #channel, /config stars <n>.

• Birthdays: /birthday set <month> <day> (only day and month are stored), /birthday remove, /birthday upcoming. Servers with birthdays on get a message at 09:00 in the server's time zone (from the QoTD step of /setup).
• Giveaways: /giveaway start <duration> <winners> <prize>, end, reroll, list. Members enter with a button (press again to leave). The draw runs from the database, so restarts don't lose giveaways.
• Mod log: deleted and edited messages, joins, leaves, bans, timeouts, nickname and role changes, channel and role changes, posted to a private channel.
• Starboard: messages with enough ⭐ reactions (default 3, not counting the author) are copied to the starboard channel.

Configuration (config.toml)

Almost everything is configurable. config.default.toml holds the built-in values (don't edit it, it ships with the code); config.toml is yours and is applied on top, so you only need the lines you want to change. A missing key keeps the default, and a value of the wrong type is ignored with a warning in aire.log. Restart after editing: sudo systemctl restart aire.

Sections: [bot] (name, prefix, owners, colour, version, token variable, service name), [tags] (the [OK]/[FAIL] prefixes), [servers] (BSS ids and invite), [commands] (disabled = [...] switches commands off), [limits] (rate limit, parrot chance, snipe time, giveaway and starboard limits), [defaults] (what new servers start with), [features] (QoTD hour/texts, birthday hour and wishes, welcome text, starboard emoji), [status] (cycling status messages), [ads], [about], [help] (category icons and names), [ai] (model, prompts, fallback questions, Claude CLI), [health], [backup], [logging]. Texts accept {prefix}, {name}, {user}, {server}, {count}, {date} where noted in the file.