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.

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.

--config-dir <configdir>

Look for configuration files in this directory.

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.

--config-dir <configdir>

Look for configuration files in this directory.

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.

--config-dir <configdir>

Look for configuration files in this directory.

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.

--config-dir <configdir>

Look for configuration files in this directory.

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.

--config-dir <configdir>

Look for configuration files in this directory.

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
option
-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.

--config-dir <configdir>

Look for configuration files in this directory.

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.

--config-dir <configdir>

Look for configuration files in this directory.

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.

--config-dir <configdir>

Look for configuration files in this directory.

-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.

--config-dir <configdir>

Look for configuration files in this directory.

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.

--config-dir <configdir>

Look for configuration files in this directory.

-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.

--config-dir <configdir>

Look for configuration files in this directory.

-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.

--config-dir <configdir>

Look for configuration files in this directory.

-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.

--config-dir <configdir>

Look for configuration files in this directory.