SOPEL(1)

NAME
sopel - Sopel IRC Bot Command Line

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

•   The sopel-config command

•   The sopel-plugins command

•   Supported environment variables

THE SOPEL COMMAND

  sopel

Sopel IRC Bot

usage: sopel [options]

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

-d, --fork
    Daemonize Sopel.

-q, --quit
    Gracefully quit Sopel (deprecated, and will be removed in Sopel 8; use sopel stop instead)

-k, --kill
    Kill Sopel (deprecated, and will be removed in Sopel 8; use sopel stop --kill instead)

-r, --restart
    Restart Sopel (deprecated, and will be removed in Sopel 8; use sopel restart instead)

-l, --list
    List all config files found(deprecated, and will be removed in Sopel 8; use sopel-config list instead)

--quiet
    Suppress all output

-w, --configure-all
    Run the configuration wizard (deprecated, and will be removed in Sopel 8; use sopel configure instead)

--configure-modules
    Run the configuration wizard, but only for the plugin configuration options (deprecated, and will be removed in Sopel 8; use sopel configure --plugins instead)

-v  Show version number and exit (deprecated, and will be removed in Sopel 8; use -V/--version instead)

-V, --version
    Show version number 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 [options] start

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

usage: sopel [options] start [-h] [-d] [--quiet] [-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).

--quiet
    Suppress all output

-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 [options] 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 [options] stop [-h] [-k] [--quiet] [-c filename]
                            [--config-dir CONFIGDIR]

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

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

--quiet
    Suppress all output

-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 [options] restart

Restart a running Sopel instance

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

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

--quiet
    Suppress all output

-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 [options] configure

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

usage: sopel [options] 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.

    New in version 7.0.

    NOTE: Any _ character in the section or setting name also appears in the environment variable name. It's therefore theoretically possible for two plugins to have section and setting name pairs that both resolve to the same environment variable name, but in practice this is highly unlikely.

    However, should such a collision occur, please notify the main Sopel project and both plugin authors via any relevant communication channel(s).

AUTHOR
Sopel contributors

COPYRIGHT
2012-2024, Sopel contributors