Command Line Interfaces#

Once installed, you can configure and start a Sopel IRC Bot instance:

$ sopel configure
# ... configuration wizard ...
$ sopel start

The configure subcommand will run a brief configuration wizard to set up the basic options: the bot’s nick, its admin’s nick, the IRC server to connect to, and channels to join. By default, it creates the file ~/.sopel/default.cfg (creating the homedir directory if necessary.)

Once this is done, the start subcommand runs the bot, using this configuration file unless one is provided using the -c/--config option.

Certain command-line options can be passed via environment variables. Also see the section on environment variables for more possibilities.

The `sopel` command#

sopel#

Sopel IRC Bot

usage: sopel [-h] [-V] {start,configure,stop,restart} ...

-h, --help#: show this help message and exit

-V, --version#: Show version number and exit

sopel start#

Start a Sopel instance. This command requires an existing configuration file that can be generated with sopel configure.

usage: sopel start [-h] [-d] [-c filename] [--config-dir CONFIGDIR]

-h, --help#: show this help message and exit

-d, --fork#: Run Sopel as a daemon (fork). This bot will safely run in the background. The instance will be named after the name of the configuration file used to run it. To stop it, use sopel stop (with the same configuration).

-c <filename>, --config <filename>#: Use a specific configuration file. A config name can be given and the configuration file will be found in Sopel’s homedir (defaults to ~/.sopel/default.cfg). An absolute pathname can be provided instead to use an arbitrary location. When the SOPEL_CONFIG environment variable is set and not empty, it is used as the default value.

--config-dir <configdir>#: Look for configuration files in this directory. By default, Sopel will search in ~/.sopel. When the SOPEL_CONFIG_DIR environment variable is set and not empty, it is used as the default value.

sopel stop#

Stop a running Sopel instance. This command determines the instance to quit by the name of the configuration file used (“default”, or the one from the -c/--config option). This command should be used when the bot is running in the background from sopel start -d, and should not be used when Sopel is managed by a process manager (like systemd or supervisor).

usage: sopel stop [-h] [-k] [-c filename] [--config-dir CONFIGDIR]

-h, --help#: show this help message and exit

-k, --kill#: Kill Sopel without a graceful quit

-c <filename>, --config <filename>#: Use a specific configuration file. A config name can be given and the configuration file will be found in Sopel’s homedir (defaults to ~/.sopel/default.cfg). An absolute pathname can be provided instead to use an arbitrary location. When the SOPEL_CONFIG environment variable is set and not empty, it is used as the default value.

--config-dir <configdir>#: Look for configuration files in this directory. By default, Sopel will search in ~/.sopel. When the SOPEL_CONFIG_DIR environment variable is set and not empty, it is used as the default value.

sopel restart#

Restart a running Sopel instance

usage: sopel restart [-h] [-c filename] [--config-dir CONFIGDIR]

-h, --help#: show this help message and exit

-c <filename>, --config <filename>#: Use a specific configuration file. A config name can be given and the configuration file will be found in Sopel’s homedir (defaults to ~/.sopel/default.cfg). An absolute pathname can be provided instead to use an arbitrary location. When the SOPEL_CONFIG environment variable is set and not empty, it is used as the default value.

--config-dir <configdir>#: Look for configuration files in this directory. By default, Sopel will search in ~/.sopel. When the SOPEL_CONFIG_DIR environment variable is set and not empty, it is used as the default value.

sopel configure#

Run the configuration wizard. It can be used to create a new configuration file or to update an existing one.

usage: sopel configure [-h] [--plugins] [-c filename] [--config-dir CONFIGDIR]

-h, --help#: show this help message and exit

--plugins#: Check for Sopel plugins that require configuration, and run their configuration wizards.

-c <filename>, --config <filename>#: Use a specific configuration file. A config name can be given and the configuration file will be found in Sopel’s homedir (defaults to ~/.sopel/default.cfg). An absolute pathname can be provided instead to use an arbitrary location. When the SOPEL_CONFIG environment variable is set and not empty, it is used as the default value.

--config-dir <configdir>#: Look for configuration files in this directory. By default, Sopel will search in ~/.sopel. When the SOPEL_CONFIG_DIR environment variable is set and not empty, it is used as the default value.

The `sopel-config` command#

New in version 7.0: The command sopel-config and its subcommands have been added in Sopel 7.0.

sopel-config#

Sopel configuration tool

usage: sopel-config [-h] {list,init,get} ...

-h, --help#: show this help message and exit

sopel-config get#

Get a configuration option’s value

usage: sopel-config get [-h] [-c filename] [--config-dir CONFIGDIR]
                        section option

section#: The name of the section to look in

option#: The name of the option to retrieve

-h, --help#: show this help message and exit

-c <filename>, --config <filename>#: Use a specific configuration file. A config name can be given and the configuration file will be found in Sopel’s homedir (defaults to ~/.sopel/default.cfg). An absolute pathname can be provided instead to use an arbitrary location. When the SOPEL_CONFIG environment variable is set and not empty, it is used as the default value.

--config-dir <configdir>#: Look for configuration files in this directory. By default, Sopel will search in ~/.sopel. When the SOPEL_CONFIG_DIR environment variable is set and not empty, it is used as the default value.

sopel-config init#

Initialize Sopel configuration file

usage: sopel-config init [-h] [-c filename] [--config-dir CONFIGDIR]

-h, --help#: show this help message and exit

-c <filename>, --config <filename>#: Use a specific configuration file. A config name can be given and the configuration file will be found in Sopel’s homedir (defaults to ~/.sopel/default.cfg). An absolute pathname can be provided instead to use an arbitrary location. When the SOPEL_CONFIG environment variable is set and not empty, it is used as the default value.

--config-dir <configdir>#: Look for configuration files in this directory. By default, Sopel will search in ~/.sopel. When the SOPEL_CONFIG_DIR environment variable is set and not empty, it is used as the default value.

sopel-config list#

List available configurations from Sopel’s config directory with the extension “.cfg”. Use option --config-dir to use a specific config directory.

usage: sopel-config list [-h] [-c filename] [--config-dir CONFIGDIR]
                         [-e EXTENSION] [-p]

-h, --help#: show this help message and exit

-c <filename>, --config <filename>#: Use a specific configuration file. A config name can be given and the configuration file will be found in Sopel’s homedir (defaults to ~/.sopel/default.cfg). An absolute pathname can be provided instead to use an arbitrary location. When the SOPEL_CONFIG environment variable is set and not empty, it is used as the default value.

--config-dir <configdir>#: Look for configuration files in this directory. By default, Sopel will search in ~/.sopel. When the SOPEL_CONFIG_DIR environment variable is set and not empty, it is used as the default value.

-e <extension>, --ext <extension>, --extension <extension>#: Filter by extension (default to “.cfg)”

-p, --path#: Display a list of absolute filenames instead of their names

The `sopel-plugins` command#

New in version 7.0: The command sopel-plugins and its subcommands have been added in Sopel 7.0.

sopel-plugins#

Sopel plugins tool

usage: sopel-plugins [-h] {show,configure,list,disable,enable} ...

-h, --help#: show this help message and exit

sopel-plugins configure#

Run a config wizard to configure a plugin.

This can be used whether the plugin is enabled or not.

usage: sopel-plugins configure [-h] [-c filename] [--config-dir CONFIGDIR]
                               name

name#: Plugin name

-h, --help#: show this help message and exit

-c <filename>, --config <filename>#: Use a specific configuration file. A config name can be given and the configuration file will be found in Sopel’s homedir (defaults to ~/.sopel/default.cfg). An absolute pathname can be provided instead to use an arbitrary location. When the SOPEL_CONFIG environment variable is set and not empty, it is used as the default value.

--config-dir <configdir>#: Look for configuration files in this directory. By default, Sopel will search in ~/.sopel. When the SOPEL_CONFIG_DIR environment variable is set and not empty, it is used as the default value.

sopel-plugins disable#

Disable a Sopel plugin by its name, no matter where it comes from.

It is not possible to disable the coretasks plugin.

usage: sopel-plugins disable [-h] [-c filename] [--config-dir CONFIGDIR] [-f]
                             [-r]
                             name [name ...]

name#: Name of the plugin to disable. Can be used multiple times to disable multiple plugins at once. In case of error, configuration is not modified.

-h, --help#: show this help message and exit

-c <filename>, --config <filename>#: Use a specific configuration file. A config name can be given and the configuration file will be found in Sopel’s homedir (defaults to ~/.sopel/default.cfg). An absolute pathname can be provided instead to use an arbitrary location. When the SOPEL_CONFIG environment variable is set and not empty, it is used as the default value.

--config-dir <configdir>#: Look for configuration files in this directory. By default, Sopel will search in ~/.sopel. When the SOPEL_CONFIG_DIR environment variable is set and not empty, it is used as the default value.

-f, --force#: Force exclusion of the plugin. When core.enable is defined, a plugin may be disabled without being excluded. In this case, use this option to force its exclusion.

-r, --remove#: Remove from core.enable list if applicable.

sopel-plugins enable#

Enable a Sopel plugin by its name, no matter where it comes from.

The coretasks plugin is always enabled.

By default, a plugin that is not excluded is enabled, unless at least one plugin is defined in the core.enable list. In that case, Sopel uses an “allow-only” policy for plugins, and all desired plugins must be added to this list.

usage: sopel-plugins enable [-h] [-c filename] [--config-dir CONFIGDIR] [-a]
                            name [name ...]

name#: Name of the plugin to enable. Can be used multiple times to enable multiple plugins at once. In case of error, configuration is not modified.

-h, --help#: show this help message and exit

-c <filename>, --config <filename>#: Use a specific configuration file. A config name can be given and the configuration file will be found in Sopel’s homedir (defaults to ~/.sopel/default.cfg). An absolute pathname can be provided instead to use an arbitrary location. When the SOPEL_CONFIG environment variable is set and not empty, it is used as the default value.

--config-dir <configdir>#: Look for configuration files in this directory. By default, Sopel will search in ~/.sopel. When the SOPEL_CONFIG_DIR environment variable is set and not empty, it is used as the default value.

-a, --allow-only#: Enforce allow-only policy. It makes sure the plugin is added to the core.enable list.

sopel-plugins list#

List available Sopel plugins from all possible sources.

Plugin sources are: built-in, from sopel_modules.*, from sopel.plugins entry points, or Sopel’s plugin directories.

Enabled plugins are displayed in green; disabled, in red.

usage: sopel-plugins list [-h] [-c filename] [--config-dir CONFIGDIR] [-C]
                          [-e | -d] [-n]

-h, --help#: show this help message and exit

-c <filename>, --config <filename>#: Use a specific configuration file. A config name can be given and the configuration file will be found in Sopel’s homedir (defaults to ~/.sopel/default.cfg). An absolute pathname can be provided instead to use an arbitrary location. When the SOPEL_CONFIG environment variable is set and not empty, it is used as the default value.

--config-dir <configdir>#: Look for configuration files in this directory. By default, Sopel will search in ~/.sopel. When the SOPEL_CONFIG_DIR environment variable is set and not empty, it is used as the default value.

-C, --no-color#: Disable colors

-e, --enabled-only#: Display only enabled plugins

-d, --disabled-only#: Display only disabled plugins

-n, --name-only#: Display only plugin names

sopel-plugins show#

Show detailed information about a plugin.

usage: sopel-plugins show [-h] [-c filename] [--config-dir CONFIGDIR] name

name#: Plugin name

-h, --help#: show this help message and exit

-c <filename>, --config <filename>#: Use a specific configuration file. A config name can be given and the configuration file will be found in Sopel’s homedir (defaults to ~/.sopel/default.cfg). An absolute pathname can be provided instead to use an arbitrary location. When the SOPEL_CONFIG environment variable is set and not empty, it is used as the default value.

--config-dir <configdir>#: Look for configuration files in this directory. By default, Sopel will search in ~/.sopel. When the SOPEL_CONFIG_DIR environment variable is set and not empty, it is used as the default value.

Supported environment variables#

`SOPEL_CONFIG`#

This environment variable replaces the built-in default config name (which is, confusingly, also “default”) if set. It’s interpreted in the same way as the -c/--config option accepted by most CLI commands described above.

New in version 7.0.

`SOPEL_CONFIG_DIR`#

This environment variable replaces the default directory in which Sopel searches for config files. It’s interpreted in the same way as the --config-dir option accepted by most CLI commands described above.

New in version 7.1.

Overriding individual settings#

Whenever a setting is accessed, Sopel looks for a matching environment variable. If found, the environment variable’s value (even if it’s empty) overrides the value from Sopel’s config file.

The variable name Sopel looks for is structured as follows:

SOPEL_ prefix (to prevent collisions with other programs)
The section name in UPPERCASE, e.g. CORE or PLUGIN_NAME
_ as separator
The setting name in UPPERCASE, e.g. NICK or API_KEY

For example, take this stripped-down config file:

[core]
nick = ConfigFileNick
host = irc.libera.chat

[plugin_name]
api_key = abad1dea

Sopel would take the nickname ConfigFileNick when connecting to IRC at irc.libera.chat, and the plugin_name plugin would use the API key abad1dea when communicating with its remote service.

However, by setting the environment variables:

SOPEL_CORE_NICK=EnvVarNick
SOPEL_PLUGIN_NAME_API_KEY=1337c0ffee9001

Sopel would take the nickname EnvVarNick when connecting to IRC (still at irc.libera.chat; that value isn’t overridden or lost), and the plugin_name plugin would use the API key 1337c0ffee9001, instead.