BlokeBotHelp & guides
Open the BlokeBot dashboard

Plugin manifest

plugin.toml

plugin.toml defines the plugin package and its declarations.

Plugin identity

Choose one stable plugin ID. Give the repository directory the same ID.

Use a semantic version and a Git tag. Do not identify the package with a commit SHA.

  • The manifest defines package identity and compatibility.
  • It defines files and settings.
  • It defines features and handlers.
  • It defines pages, public overlay widgets and automations.
  • It defines migrations.
manifestVersion = 1
id = "community.my-plugin"
name = "My plugin"
description = "Adds one documented channel tool."
entryModule = "main"

[marketplace]
author = "Plugin author"
tags = ["example"]
mediaUrls = []

[release]
declaredVersion = "0.1.0"
tag = "community-my-plugin-v0.1.0"

Compatibility

Each target for an asset or payload must also appear in the top-level target list.

  • Declare one API range and one BlokeBot version range.
  • Declare Lua 5.4.
  • Declare every supported runtime target.
[compatibility]
minimumApiVersion = 1
maximumApiVersion = 1
minimumBlokeBotVersion = "0.13.0"
maximumBlokeBotVersionExclusive = "0.14.0"
luaVersion = "lua54"
supportedTargets = [
  "linux-x64",
  "linux-arm64",
  "osx-arm64",
  "win-x64",
  "win-arm64",
]

Package files

  • The package validator rejects undeclared files.
  • The package validator rejects missing files.
  • The package validator rejects unsafe paths.
  • The package validator rejects links.
  • The package validator rejects path collisions.
  • The package validator rejects incompatible targets.
  • Each listed browser or media file declares its media type.
  • Each listed browser or media file declares its purpose.
  • Each listed browser or media file declares its targets.
  • Each listed browser or media file declares its maximum size.
luaModules
Lists each Lua module and its package path.
assets
Lists browser or media files with their asset declarations.
payloads
Lists other reviewed files and their runtime targets.
[[luaModules]]
id = "main"
path = "lua/main.lua"

[[assets]]
id = "page-document"
path = "web/index.html"
kind = "browser"
mediaType = "text/html"
purpose = "Provides the plugin page."
runtimeIdentifiers = ["linux-x64"]
maximumBytes = 65536

Settings and features

Installation settings apply to the plugin installation. Channel settings apply to one feature on one BlokeBot host.

BlokeBot protects a secret at rest. It never returns the saved value to an administrator page.

text
A bounded single-line string.
multilineText
A bounded multiline string.
integer
A bounded integer.
number
A bounded finite number.
boolean
A true or false value.
choice
One value from declared choices.
duration
A duration within declared second limits.
secret
A protected bounded string.
[[settings]]
id = "response-message"
name = "Response message"
description = "Sets the command response."
scope = "channel"
required = false

[settings.schema]
kind = "text"
maximumLength = 500

[[features]]
id = "starter"
name = "Starter command"
description = "Replies to one command."
settings = ["response-message"]
automationTemplates = []

Public overlay widgets

A widget is not a management page. Declare its feature, Lua render entry point, HTML document asset and every additional browser asset it may use.

Use public-safe configuration defaults. The browser receives only the projected public result and scoped, short-lived GET-only URLs for declared assets, not installation settings, page sessions or dashboard actions.

Configuration portability is optional host-side metadata. Mark values portable only when the entire value, including nested maps and arrays, is safe to transfer. Destination bindings and withheld, undeclared or unknown values are omitted from full-document transfer.

An imported widget retains layout, audio and source but needs explicit destination setup, even when omitted fields are optional. Old manifests remain locally usable. Older hosts reject the new TOML keys; set the appropriate minimum BlokeBot version when using them.

[[widgets]]
id = "public-display"
featureId = "starter"
title = "Public display"
module = "main"
renderEntryPoint = "render_widget"
documentAsset = "widget-document"
assets = ["widget-script"]
defaultConfiguration = { text = "Welcome" }

[[widgets.configurationFields]]
name = "text"
title = "Public heading"
valueKind = "string"
required = true
portability = "portable"

[[widgets.configurationFields]]
name = "destination"
title = "Destination binding"
valueKind = "string"
required = false
portability = "destinationBinding"

Host modules

Declare every standard host module that the Lua code calls. Set the supported API range for each module.

[[hostModules]]
id = "settings"
minimumVersion = 1
maximumVersion = 1

[[hostModules]]
id = "responses"
minimumVersion = 1
maximumVersion = 1

Manifest validation

  1. Run blokebot-plugin generate after each manifest change.
  2. Fix each manifest or package error.
  3. Run blokebot-plugin validate for all supported targets.
  4. If tests.toml exists, run blokebot-plugin test.