Skip to main content
`Ctrl`+`K`

# Hook Plugin

Internally, beets uses events to tell plugins when something happens. For example, one event fires when the importer finishes processes a song, and another triggers just before the `beet` command exits. The `hook` plugin lets you run commands in response to these events.

## Configuration

To configure the plugin, make a `hook` section in your configuration file. The available options are:

- hooks: A list of events and the commands to run (see Configuring Each Hook). Default: Empty.

### Configuring Each Hook

Each element under `hooks` should have these keys:

- event: The name of the event that will trigger this hook. See the plugin events documentation for a list of possible values.

- command: The command to run when this hook executes.

### Command Substitution

Commands can access the parameters of events using Python string formatting. Use `{name}` in your command and the plugin will substitute it with the named value. The name can also refer to a field, as in `{album.path}`.

You can find a list of all available events and their arguments in the plugin events documentation.

## Example Configuration

    hook:
      hooks:
        # Output on exit:
        #   beets just exited!
        #   have a nice day!
        - event: cli_exit
          command: echo "beets just exited!"
        - event: cli_exit
          command: echo "have a nice day!"

        # Output on item import:
        #   importing "<file_name_here>"
        # Where <file_name_here> is the item being imported
        - event: item_imported
          command: echo "importing \"{item.path}\""

        # Output on write:
        #   writing to "<file_name_here>"
        # Where <file_name_here> is the file being written to
        - event: write
          command: echo "writing to {path}"