Skip to main content
`Ctrl`+`K`

# Add Commands to the CLI

Plugins can add new subcommands to the `beet` command-line interface. Define the plugin class’ `commands()` method to return a list of `Subcommand` objects. (The `Subcommand` class is defined in the `beets.ui` module.) Here’s an example plugin that adds a simple command:

    from beets.plugins import BeetsPlugin
    from beets.ui import Subcommand

    my_super_command = Subcommand("super", help="do something super")

    def say_hi(lib, opts, args):
        print("Hello everybody! I'm a plugin!")

    my_super_command.func = say_hi

    class SuperPlug(BeetsPlugin):
        def commands(self):
            return [my_super_command]

To make a subcommand, invoke the constructor like so: `Subcommand(name, parser, help, aliases)`. The `name` parameter is the only required one and should just be the name of your command. `parser` can be an OptionParser instance, but it defaults to an empty parser (you can extend it later). `help` is a description of your command, and `aliases` is a list of shorthand versions of your command name.

You’ll need to add a function to your command by saying `mycommand.func = myfunction`. This function should take the following parameters: `lib` (a beets `Library` object) and `opts` and `args` (command-line options and arguments as returned by OptionParser.parse_args).

The function should use any of the utility functions defined in `beets.ui`. Try running `pydoc beets.ui` to see what’s available.

You can add command-line options to your new command using the `parser` member of the `Subcommand` class, which is a `CommonOptionsParser` instance. Just use it like you would a normal `OptionParser` in an independent script. Note that it offers several methods to add common options: `--album`, `--path` and `--format`. This feature is versatile and extensively documented, try `pydoc beets.ui.CommonOptionsParser` for more information.