Table of Contents

  1. List of Commands
  2. Module Development
  3. Managing MirahezeBot (for maintainers)
    1. Restarting MirahezeBot
    2. Improving Modules
    3. Configuration Changes
    4. Canceling Reminders
    5. Website Updates

List of Commands

Commands Purpose Example Plugin
.isblocked No documentation found. Sygnal
.channels No documentation found. Sygnal
.addpattern No documentation found. Sygnal
.proxycheck No documentation found. Sygnal
.reset No documentation found. Sygnal
.join Join the specified channel. This is an admin-only command. .join #example admin
.me Send an ACTION (/me) to a given channel or nick. Can only be done in
privmsg by an admin.
admin
.mode Set a user mode on Sopel. Can only be done in privmsg by an admin. admin
.part Part the specified channel. This is an admin-only command. .part #example admin
.quit Quit from the server. This is an owner-only command. admin
.restart Restart the bot. This is an owner-only command. admin
.save Save state of Sopel's config object to the configuration file. .save admin
.say
.msg
Send a message to a given channel or nick. Can only be done in privmsg by
an admin.
.say #YourPants Does anyone else smell neurotoxin? admin
.set See and modify values of Sopel's config object.

Trigger args:
arg1 - section and option, in the form "section.option"
arg2 - value

If there is no section, section will default to "core".
If value is not provided, the current value will be displayed.
.set core.owner MyNick admin
.tmpjoin Like join, without saving. This is an admin-only command.

Unlike the join command, tmpjoin won't remember the channel upon
restarting the bot.
.tmpjoin #example admin
.tmppart Like part, without saving. This is an admin-only command.

Unlike the part command, tmppart will rejoin the channel upon
restarting the bot.
.tmppart #example admin
.unset Unset value of Sopel's config object.

Unsetting a value will reset it to the default specified in the config
definition.

Trigger args:
arg1 - section and option, in the form "section.option"

If there is no section, section will default to "core".
.unset core.owner admin
.accesslevel
.access
Tell user what access level they have for the bot. adminlist
.botadmins
.admins
Provide the list of bot admins. adminlist
.announce Send an announcement to all channels the bot is in .announce Some important message here announce
.c
.calc
Evaluate some calculation. .c 5 / 2 calc
.ban Ban a user from the channel. The bot must be a channel operator for this command to work. .ban Zppix channelmgnt
.chanmode Command to change channel mode. .chanmode +mz channelmgnt
.deop Command to deop users in a room. If no nick is given, Sopel will deop the nick who sent the command .deop Zppix channelmgnt
.devoice Command to devoice users in a room. If no nick is given, the nick who sent the command will be devoiced .devoice Zppix channelmgnt
.invite Command to invite users to a room. channelmgnt
.kick Kick a user from the channel. .kick Zppix channelmgnt
.kickban
.kb
Kick and ban a user from the channel. The bot must be a channel operator for this command to work.
.kickban [#chan] user1 user!*@* get out of here channelmgnt
.op Command to op users in a room. If no nick is given, Sopel will op the nick who sent the command .op Zppix channelmgnt
.quiet Quiet a user. The bot must be a channel operator for this command to work.
.quiet Zppix channelmgnt
.tmask Set the topic mask to use for the current channel. Within the topic mask, {} is used to allow substituting in chunks of text. This mask is used when running the 'topic' command.
.tmask Welcome to My Channel | Info: {} channelmgnt
.showmask Show the topic mask for the current channel. channelmgnt
.topic Change the channel topic. The bot must be a channel operator for this command to work.
.topic Your Great New Topic channelmgnt
.unban Unban a user from the channel. The bot must be a channel operator for this command to work.
.unban Zppix channelmgnt
.unquiet Unquiet a user. The bot must be a channel operator for this command to work.
.unquiet Zppix channelmgnt
.voice Command to voice users in a room. If no nick is given, Sopel will voice the nick who sent the command .voice Zppix channelmgnt
.choose
.ch
.choice
.choice option1|option2|option3 - Makes a difficult choice easy. .choose a choose
.t
.time
Return the current time.

The command takes an optional parameter: it will try to guess if it's a
nick, a channel, or a timezone (in that order).

If it's a known nick or channel but there is no configured timezone, then
it will complain. If nothing can be found, it'll complain that the argument
is not a valid timezone.

.. seealso::

Function :func:~sopel.tools.time.format_time is used to format
the current datetime according to the timezone (if found).
.t #sopel clock
.tz
.timez
Return the current time in a timezone.

Unlike the .t command, it requires an argument, and that argument
must be a valid timezone.
.tz America/New_York clock
.getchanneltimeformat
.getctf
Gets the channel's preferred time format; will return current channel's if
no channel name is given.
.getctf [channel] clock
.getchanneltz
.getctz
Gets the channel's preferred timezone; returns the current channel's
if no channel name is given.
.getctz [channel] clock
.gettimeformat
.gettf
Gets a user's preferred time format; will show yours if no user specified. .gettf [nick] clock
.gettz
.gettimezone
Gets a user's preferred time zone; will show yours if no user specified. .gettz [nick] clock
.setchanneltz
.setctz
Set the preferred timezone for the channel. .setctz America/New_York clock
.setchanneltimeformat
.setctf
Sets your preferred format for time. Uses the standard strftime format. You
can use http://strftime.net or your favorite search engine to learn more.
.setctf %Y-%m-%dT%T%z clock
.settz
.settimezone
Set your preferred timezone.

Most timezones will work, but it's best to use one from
https://sopel.chat/tz.
.settz America/New_York clock
.settimeformat
.settf
Sets your preferred format for time. Uses the standard strftime format. You
can use http://strftime.net or your favorite search engine to learn more.
.settf %Y-%m-%dT%T%z clock
.countdown .countdown (year) (month) (day) - displays a countdown to a given date. countdown
.cur
.currency
.exchange
No documentation found. .cur 100 usd in btc cad eur can aux currency
.d
.dice
.roll
.dice XdY[vZ][+N][#COMMENT], rolls dice and reports the result.

X is the number of dice. Y is the number of faces in the dice. Z is the
number of lowest dice to be dropped from the result. N is the constant to
be applied to the end result. Comment is for easily noting the purpose.
.roll 1d6 # initiative dice
.afraid No documentation found. .afraid emoticons
.rage
.anger
No documentation found. .anger emoticons
.crazy No documentation found. .crazy emoticons
.cry No documentation found. .cry emoticons
.happy No documentation found. .happy emoticons
.hungry No documentation found. .hungry emoticons
.lenny No documentation found. .lenny emoticons
.love No documentation found. .love emoticons
.shrug No documentation found. .shrug emoticons
.sick No documentation found. .sick emoticons
.success
.winner
No documentation found. .winner emoticons
.surprised No documentation found. .surprised emoticons
.tableflip
.tflip
No documentation found. .tflip emoticons
.unflip No documentation found. .unflip emoticons
.confused
.wat
No documentation found. .wat emoticons
.worried No documentation found. .worried emoticons
.ety Look up the etymology of a word .ety word etymology
.burger Makes me give the specified nick a burger. .burger MirahezeBot goofy
.coffee Makes me give the specified nick a coffee. .coffee MirahezeBot goofy
.hotchoc
.hotchocolate
Makes me give the specified nick a hot chocolate. .hotchoc MirahezeBot goofy
.hug Makes me give the specified nick a hug. .hug MirahezeBot goofy
.present Makes me give the specified nick a present. .present MirahezeBot goofy
.help
.commands
Shows a command's documentation, and an example if available. With no arguments, lists all commands. .help tell help
.invite Invite the given user to the current channel, or (with optional
second argument) another channel that Sopel is in.
.invite converge #sopel invite
.iplookup
.ip
IP Lookup tool .ip 8.8.8.8 ip
.isup Check if a website is up or not. isup
.isupinsecure Check if a website is up (without verifying HTTPS). isup
.joinall Join some channels. join
.lmgtfy
.lmgify
.gify
.gtfy
Let me just… Google that for you. .lmgtfy lmgtfy
.chairs Set the meeting chairs. .chairs Tyrope Jason elad meetbot
.endmeeting End a meeting. .endmeeting meetbot
.listactions No documentation found. .listactions meetbot
.action Log an action in the meeting log. .action elad will develop a meetbot meetbot
.agreed Log an agreement in the meeting log. .agreed Bowties are cool meetbot
.info Log an informational item in the meeting log. .info all board members present meetbot
.link Log a link in the meeing log. .link http://example.com meetbot
.subject Change the meeting subject. .subject roll call meetbot
.comments Show the comments that have been logged for this meeting with .comment. meetbot
.startmeeting Start a meeting. .startmeeting Meeting Title meetbot
.comment Log a comment, to be shown with other comments when a chair uses .comments.
Intended to allow commentary from those outside the primary group of people
in the meeting.

Used in private message only, as .comment <#channel> <comment to add>
meetbot
.highpri Command to find high priority tasks whithout updates for a while. .highpri 2 phab
.task Get a Miraheze phabricator link to a the task number you provide. .task 1 phab
.miraheze Miraheze about command.

This command will tell you about Miraheze and where to learn more.
.miraheze miraheze
.discord Displays discord information for Miraheze. miraheze
.gethelp Reply to help requests. .gethelp I cannot access https://meta.miraheze.org miraheze
.ping Reply to ping command. pingpong
.pronouns No documentation found. .pronouns Embolalia pronouns
.setpronouns No documentation found. .setpronouns they/them/their/theirs/themselves pronouns
.py Evaluate a Python expression. .py len([1,2,3]) py
.delete Deletes provided key from quote database .delete a quotes
.match Search for keys that match the pattern .match pattern quotes
.quote Add a quote, or return the quote for the provided key, or return a random quote .quote
.quote a
.quote a = b
quotes
.rand Replies with a random number between first and second argument. .rand 10 99 rand
.load Loads a module (for use by admins only). reload
.reload Reloads a module (for use by admins only). reload
.update Pulls the latest versions of all modules from Git (for use by admins only). reload
.at Gives you a reminder at the given time.

Takes hh:mm:ssTimezone Date message where seconds, Timezone, and Date
are optional.

Timezone is any timezone Sopel takes elsewhere; the best choices are those
from the tzdb; a list of valid options is available at
https://sopel.chat/tz.

The Date can be expressed in one of these formats: YYYY-mm-dd, dd-mm-YYYY,
dd-mm-YY, or dd-mm. The separator can be ., -, or /.
.at 00:01 25/12 Open your gift! remind
.in Gives you a reminder in the given amount of time. .in 3h45m Go to class remind
.addchannel Reply to channel request message. .addchannel (insert which) responses
.botversion
.bv
List the current version of the bot. .botversion responses
.cancelreminder Cancel reminder. .cancelreminder (insert reminder message here) responses
.source
.botsource
Give the link to MirahezeBot's Github. .source responses
.gj
.gw
Tell the user that they are doing good work. .gj (nick) responses
.bing Queries Bing for the specified input. .bing sopel irc bot search
.duck
.ddg
.g
Queries DuckDuckGo for the specified input. .duck sopel.chat irc bot search
.search Searches both Bing and DuckDuckGo. .search sopel irc bot search
.suggest Suggests terms starting with given input .suggest lkashdfiauwgeaef search
.seen Reports when and where the user was last seen. seen
.github
.gh
Expands a link to github. .github user shortlinks
.mhca Expands a link to Miraheze Central Auth. .mhca example shortlinks
.mh Expands a link to Miraheze wikis. .mh wiki page shortlinks
.subred Expands a link to reddit/r. .subred example shortlinks
.redditu Expands a link to reddit/u. .redditu example shortlinks
.tw Expands a link to Twitter. .tw user shortlinks
.wmca Expands a link to Wikimedia CentralAuth. .wmca example shortlinks
.status Update's the /status subpage of Special:MyPage on the indicated wiki .status mhtest offline status
.stock No documentation found. .stock msft stocks
.tell
.ask
Give someone a message the next time they're seen Sopel, tell dgw he broke something again. tell
.tld Show information about the given Top Level Domain. .tld ru tld
.mangle
.mangle2
Repeatedly translate the input until it makes absolutely no sense. translate
.translate
.tr
Translates a phrase, with an optional language hint. .tr mon chien translate
.u Look up a Unicode character or a hexadecimal code point. .u 203D unicode_info
.length
.distance
Convert distances .length 3 parsec units
.weight
.mass
Convert mass units
.temp Convert temperatures .temp 100K units
.uptime .uptime - Returns the uptime of Sopel. uptime
.title Show the title or URL information for the given URL, or the last URL seen
in this channel.
.title http://google.com url
.url Allow a bot admin to modify the url blacklist. Accepts ban, allow and match as parameters. .url ban http://google.com url
.version Display the latest commit version, if Sopel is running in a git repo. version
.forecast Show the weather forecast for tomorrow at the given location. .forecast Dallas, TX, US
.forecast London, UK
weather
.setlocation Set your default weather location. .setlocation Dallas, TX, US
.setlocation London, UK
weather
.weather
.wea
Show the weather at the given location. .weather Dallas, TX, US
.weather London, UK
weather
.add_known
.adduser
Add user to known users list. .add_known Zppix #miraheze or .adduser Zppix #miraheze welcome
.w
.wiki
.wik
No documentation found. .w San Francisco wikipedia
.wt
.define
.dict
Look up a word on Wiktionary. .wt bailiwick wiktionary
.youtube
.yt
Search YouTube .yt how to be a nerdfighter FAQ youtube
.xkcd .xkcd - Finds an xkcd comic strip.

Takes one of 3 inputs:

* If no input is provided it will return a random comic
* If numeric input is provided it will return that comic, or the
nth-latest comic if the number is non-positive
* If non-numeric input is provided it will return the first search result
for those keywords on the xkcd.com site
xkcd
.blocks Manage Sopel's blocking features. coretasks
.useserviceauth No documentation found. coretasks
.execute Execute commands specified to perform on IRC server connect. coretasks

Module Development

If you decided to extend MirahezeBot with some functionality, you will need to create a new module.
This instruction will guide you through the process of custom module development
First of all, create a new file in modules directory with name your_module.py
Bot modules are python scripts, so we shall start with importing required libraries (bot is using sopel) for your module to work. Here is the list of imports typically used:
    from __future__ import unicode_literals, absolute_import, print_function, division
    import sopel
    import sopel.module
    import requests
    import sopel.tools
    from sopel.module import rule, priority, thread, commands, example
    
Let's define a function, which replies to ".hi" command with a greeting:
    @commands('hi')
    def bot_hi(bot, trigger):
        bot.say('Hi ' + trigger.nick + '!')
    
Explanation: using @commands we specify which command bot should react to (in our case ".hi")
Handler function has two parameters:
So in our example, we use bot.say to send message to the chat saying "hi, your_name!"
This is minimum required code for your module to function. You may try running it now.

Unluckily, our bot will react only to ".hi" messages, but you may want it to react to ".hello" and ".hey" as well
In order to achieve that, we may set multiple command variations bot will respond to by specifying all of them in the decorator:
    @commands('hi', 'hello', 'hey')
    def bot_hi(bot, trigger):
        bot.say('Hi ' + trigger.nick + '!')
    
You may try running that code and see that bot will react to all commands mentioned by saying "hi" to message sender.
Finally, you may want bot to accept some input from user. To demonstrate how to achieve that, let's develop a function which will welcome chat newcomers
For example, if John joins your chat, you may ask bot to welcome him with command ".welcome John" and bot will send a message saying "Welcome, John! Enjoy yourself in this chat!"
Similarly, you may ask bot to welcome Bob my saying ".welcome Bob" and bot will say "Welcome, Bob! Enjoy yourself in this chat!"
Let's also use @example decorator to provide command usage example:
    @commands('welcome')
    @example('.welcome John')
    def bot_welcome(bot, trigger):
        bot.say('Welcome ' + trigger.group(2) + '! Enjoy yourself in this chat!')
    
Explanation: we use trigger.group(2) to get the text after the command (in our example - name of user to welcome)

Additionally, you may use bot.reply, which is similar to bot.say, but puts message sender name in the beginning of the message
To demonstrate that, let's create an "echo" function - it will send back to you your message, which will be starting with you name (i.e mention you):
    @commands('echo')
    @example('.echo hello world!')
    def bot_welcome(bot, trigger):
        bot.reply('You said: ' + trigger.group(2))
    
That was an example of simple module. We recommend you visiting Sopel Wiki for more info on this topic.

Complete source code of this example (file simple_module.py):
    from __future__ import unicode_literals, absolute_import, print_function, division
    import sopel
    import sopel.module
    import requests
    import sopel.tools
    from sopel.module import rule, priority, thread, commands, example

    @commands('hi', 'hello', 'hey')
    def bot_hi(bot, trigger):
        bot.say('Hi ' + trigger.nick + '!')


    commands('welcome')
    @example('.welcome John')
    def bot_welcome(bot, trigger):
        bot.say('Welcome ' + trigger.group(2) + '! Enjoy yourself in this chat!')


    @commands('echo')
    @example('.echo hello world!')
    def bot_welcome(bot, trigger):
        bot.reply('You said: ' + trigger.group(2))
    

Managing MirahezeBot (for maintainers)

Restarting MirahezeBot

To restart the bot first ssh to 100.node4.net.fosshost.org.
ssh (your username)@100
Run the following command:
(your username)@100:~$ sudo /usr/sbin/service [mirahezebot|mirahezebottest] [stop|start|restart]

Improving Modules

See https://bots.miraheze.org/wiki/Deploying_Changes

Configuration Changes

1. ssh into the server
2. cd into /srv/sopelbots/[test|prod]
3. Make any necessary changes to the config by editing default.cfg (ie: nano default.cfg or vim default.cfg) and save the file.
4. Restart the bot using the guide above.

Canceling Reminders

To cancel a reminder first connect to the server.
ssh (your username)@100.node4.net.fosshost.org
(your username)@100:~$
Next cd into /srv/sopelbots/[test|prod] and edit *-chat.freenode.net.reminders.db and remove the entry for the reminder you want to cancel, and save the file.
(your username)t@100:~$ cd /srv/sopelbots/[test|prod]
(your username)@100:~/.sopel$ nano *-chat.freenode.net.reminders.db
Finally, follow the guide to restart the bot above.

Website Updates

For most changes, simply merging will deploy within ~20 mins. If you can not use auto-deploy or it is down, merge your change on GitHub. Next ssh to the server.
ssh (your username)@100.node4.net.fosshost.org
Next run deploy.py. This will pull in any new changes to the repository on GitHub.
(your username)@100:~$ python3 /var/www/deploy.py 
Go to bots.miraheze.wiki and check to make sure your changes are present.