Writing Scripts

This guide walks you through writing scripts for Flume, from basic event handling to advanced patterns like custom commands with help text, persistent config, buffer management, and more.

Vault access: Autoload scripts run after the vault is unlocked, so flume.vault.get() works at module load time. You can safely read secrets at the top level of your script.

Script errors: Load failures and runtime errors are displayed as system messages in the flume buffer with full tracebacks — no need to check log files.

Script Structure

Every script follows the same pattern:

Import the flume module (Python only — Lua has it globally)
Register event handlers and/or custom commands
Flume calls your handlers when events occur

Lua:

-- my_script.lua
flume.event.on("message", function(e)
    -- handle the event
end)

flume.command.register("mycommand", function(args)
    -- handle the command
end, "Help text for /mycommand")

Python:

# my_script.py
import flume

def on_message(e):
    # handle the event
    pass

flume.event.on("message", on_message)

def my_command(args):
    # handle the command
    pass

flume.command.register("mycommand", my_command, "Help text for /mycommand")

Custom Commands with Help

The third argument to flume.command.register is the help text shown when users type /help <command>: Lua:

flume.command.register("weather", function(args)
    if args == "" then
        flume.buffer.print("", "", "Usage: /weather <city>")
        return
    end
    flume.buffer.print("", "", "Checking weather for " .. args .. "...")
    -- your logic here
end, "Check weather for a city. Usage: /weather <city>")

Python:

def weather(args):
    if not args.strip():
        flume.buffer.print("", "", "Usage: /weather <city>")
        return
    flume.buffer.print("", "", f"Checking weather for {args}...")

flume.command.register("weather", weather, "Check weather for a city. Usage: /weather <city>")

Now /help weather shows: /weather — Check weather for a city. Usage: /weather <city>

Printing to Buffers

flume.buffer.print(server, buffer, text) prints a message to a specific buffer. Use empty strings "" for the active server/buffer:

-- Print to the active buffer
flume.buffer.print("", "", "Hello!")

-- Print to a specific channel on the active server
flume.buffer.print("", "#flume", "Message to #flume")

-- Print to a specific server and channel
flume.buffer.print("libera", "#rust", "Message to libera/#rust")

Switching Buffers

flume.buffer.switch("#flume")

Sending Messages

-- Send a channel message
flume.channel.say("", "#flume", "Hello everyone!")

-- Send to a specific server
flume.channel.say("libera", "#rust", "Hello from a script!")

-- Join/part channels
flume.channel.join("", "#newchannel")
flume.channel.part("", "#oldchannel", "Goodbye!")

Persistent Script Config

Scripts can store and retrieve configuration values that persist across sessions using flume.config.get/set. Each script gets its own config file at ~/.local/share/flume/scripts/data/<scriptname>/config.toml. Lua:

-- Save a value
flume.config.set("api_key", "abc123")
flume.config.set("enabled", true)
flume.config.set("max_results", 10)

-- Read a value (returns nil if not set)
local key = flume.config.get("api_key")
local enabled = flume.config.get("enabled")

-- Use with a default
local limit = flume.config.get("max_results") or 5

Python:

# Save a value
flume.config.set("api_key", "abc123")
flume.config.set("enabled", True)

# Read a value (returns None if not set)
key = flume.config.get("api_key")
limit = flume.config.get("max_results") or 5

Reading Vault Secrets

Scripts can read secrets stored in the encrypted vault via flume.vault.get(name). This is useful for scripts that need API keys, passwords, or tokens without hardcoding them. Store secrets first:

/secure set x_username myuser
/secure set x_password mypassword
/secure set totp_seed JBSWY3DPEHPK3PXP

Lua:

local username = flume.vault.get("x_username")
local password = flume.vault.get("x_password")
local seed = flume.vault.get("totp_seed")

if not username then
    flume.buffer.print("", "", "Missing vault secret: x_username")
    flume.buffer.print("", "", "Run: /secure set x_username <value>")
    return
end

Python:

username = flume.vault.get("x_username")
password = flume.vault.get("x_password")
seed = flume.vault.get("totp_seed")

if not username:
    flume.buffer.print("", "", "Missing vault secret: x_username")
    flume.buffer.print("", "", "Run: /secure set x_username <value>")

Returns nil (Lua) or None (Python) if the secret doesn’t exist.

Vault secrets are read-only from scripts. Use /secure set to store them. Be careful not to print secrets to buffers — other users can see channel messages.

Sending Desktop Notifications

flume.ui.notify("You were mentioned in #flume!")
flume.ui.notify("Important alert", "warning")  -- with level

Sending Raw IRC Commands

For anything not covered by the API, send raw IRC protocol lines:

-- Send a raw line to the active server
flume.server.send_raw("", "PRIVMSG NickServ :IDENTIFY mypassword")

-- Send to a specific server
flume.server.send_raw("libera", "OPER myname mypassword")

Event Cancellation

Scripts can cancel events to prevent them from being displayed: Lua:

-- Spam filter: hide messages containing certain words
flume.event.on("message", function(e)
    local blocked = {"spam", "advertisement", "buy now"}
    for _, word in ipairs(blocked) do
        if e.text:lower():find(word) then
            e:cancel()
            return
        end
    end
end)

Python:

def spam_filter(e):
    blocked = ["spam", "advertisement", "buy now"]
    text = e.get("text", "").lower()
    for word in blocked:
        if word in text:
            e["_cancel"] = True
            return

flume.event.on("message", spam_filter)

Practical Examples

Auto-Reply When Away

-- away_auto.lua — Auto-reply when mentioned while away
local away = false
local away_msg = "I'm away from keyboard"

flume.command.register("setaway", function(args)
    if args == "" then
        away = not away
        flume.buffer.print("", "", away and "Away mode ON" or "Away mode OFF")
    else
        away = true
        away_msg = args
        flume.buffer.print("", "", "Away: " .. args)
    end
end, "Toggle away auto-reply. /setaway [message]")

flume.event.on("private_message", function(e)
    if away then
        flume.channel.say(e.server, e.nick, away_msg)
    end
end)

Channel Logger

-- chanlog.lua — Log specific channels to per-script config
flume.event.on("message", function(e)
    local channels = flume.config.get("channels") or ""
    if channels:find(e.channel) then
        local line = os.date("%Y-%m-%d %H:%M:%S") .. " <" .. e.nick .. "> " .. e.text
        flume.buffer.print("", "", "[log] " .. line)
    end
end)

flume.command.register("logchan", function(args)
    if args == "" then
        local channels = flume.config.get("channels") or "(none)"
        flume.buffer.print("", "", "Logging channels: " .. channels)
    else
        flume.config.set("channels", args)
        flume.buffer.print("", "", "Now logging: " .. args)
    end
end, "Set channels to log. /logchan #chan1 #chan2")

Nick Highlighter with Sound

-- nickalert.lua — Extra alerts for specific nicks
flume.event.on("message", function(e)
    local watch_list = flume.config.get("nicks") or ""
    for nick in watch_list:gmatch("%S+") do
        if e.nick:lower() == nick:lower() then
            flume.ui.notify(e.nick .. " said: " .. e.text)
            flume.buffer.print(e.server, e.channel,
                "[alert] " .. e.nick .. ": " .. e.text)
        end
    end
end)

flume.command.register("watchnick", function(args)
    if args == "" then
        local nicks = flume.config.get("nicks") or "(none)"
        flume.buffer.print("", "", "Watching: " .. nicks)
    else
        flume.config.set("nicks", args)
        flume.buffer.print("", "", "Now watching: " .. args)
    end
end, "Watch for messages from specific nicks. /watchnick nick1 nick2")

Python: URL Title Fetcher (with pip packages)

Python scripts have full import access — use any pip package:

# urltitle.py — Fetch and display URL titles
import flume
import re

try:
    import requests
    from bs4 import BeautifulSoup
    HAS_DEPS = True
except ImportError:
    HAS_DEPS = False

URL_RE = re.compile(r'https?://\S+')

def on_message(e):
    if not HAS_DEPS:
        return
    urls = URL_RE.findall(e.get("text", ""))
    for url in urls[:2]:  # max 2 per message
        try:
            resp = requests.get(url, timeout=5, headers={"User-Agent": "Flume IRC"})
            soup = BeautifulSoup(resp.text, "html.parser")
            title = soup.title.string.strip() if soup.title else None
            if title:
                flume.buffer.print(e["server"], e["channel"],
                    f"[title] {title}")
        except Exception:
            pass

flume.event.on("message", on_message)

def check_deps(args):
    if HAS_DEPS:
        flume.buffer.print("", "", "urltitle: dependencies OK (requests, beautifulsoup4)")
    else:
        flume.buffer.print("", "", "urltitle: missing deps. Run: pip install requests beautifulsoup4")

flume.command.register("urltitle", check_deps, "Check URL title fetcher dependencies")

Managing Autoload

/script load myscript          # load a script
/script autoload myscript      # symlink into autoload dir (loads on startup)
/script noautoload myscript    # remove from autoload
/script unload myscript        # unload from current session
/script list                   # see loaded scripts and their commands

Debugging Tips

Use flume.buffer.print("", "", "debug: " .. variable) to print debug info
Check /script list to verify your script loaded
Check the Flume log at ~/.local/share/flume/logs/flume.log for errors
Reload after changes: /script reload myscript
Python import errors show as load failures — check that deps are installed

Getting Started

Configuration

Scripting

Commands

Writing Scripts

Script Structure

Custom Commands with Help

Printing to Buffers

Switching Buffers

Sending Messages

Persistent Script Config

Reading Vault Secrets

Sending Desktop Notifications

Sending Raw IRC Commands

Event Cancellation

Practical Examples

Auto-Reply When Away

Channel Logger

Nick Highlighter with Sound

Python: URL Title Fetcher (with pip packages)

Managing Autoload

Debugging Tips

​Script Structure

​Custom Commands with Help

​Printing to Buffers

​Switching Buffers

​Sending Messages

​Persistent Script Config

​Reading Vault Secrets

​Sending Desktop Notifications

​Sending Raw IRC Commands

​Event Cancellation

​Practical Examples

​Auto-Reply When Away

​Channel Logger

​Nick Highlighter with Sound

​Python: URL Title Fetcher (with pip packages)

​Managing Autoload

​Debugging Tips

Script Structure

Custom Commands with Help

Printing to Buffers

Switching Buffers

Sending Messages

Persistent Script Config

Reading Vault Secrets

Sending Desktop Notifications

Sending Raw IRC Commands

Event Cancellation

Practical Examples

Auto-Reply When Away

Channel Logger

Nick Highlighter with Sound

Python: URL Title Fetcher (with pip packages)

Managing Autoload

Debugging Tips