CLI command plugins - Betty documentation

Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# CLI command plugins

Type | `betty.cli.commands.Command`
Repository | `betty.cli.commands.COMMAND_REPOSITORY`

Betty’s Command Line Interface allows you to run Betty by invoking commands. These commands are built using Click.

## Creating a command

1. Create a new asynchronous function, decorated with `betty.cli.commands.command()` (which works almost identically to `click.command()`), for example:

       from betty.cli.commands import command

       @command
       async def my_command() -> None:
         # Do what your command needs to do here...
         ...

2. Tell Betty about your command by registering it as an entry point. Given the command above in a module `my_package.my_module`, add the following to your Python package:

pyproject.toml

    [project.entry-points.'betty.command']
    'my-command' = 'my_package.my_module.my_command'

setup.py

    SETUP = {
        'entry_points': {
            'betty.command': [
                'my-command=my_package.my_module.my_command',
            ],
        },
    }
    if __name__ == '__main__':
        setup(**SETUP)

### Accessing the project

To make your command use a specific Betty project, use the `betty.cli.commands.pass_project()` decorator:

    from betty.project import Project
    from betty.cli.commands import command, pass_project

    @command
    @pass_project
    async def my_command(project: Project) -> None:
      # Do what your command needs to do here...
      ...

This also gives you access to the Betty application through `betty.project.Project.app`.

### Accessing the project

If your command does not need a project, but does require the Betty application, use the `betty.cli.commands.pass_app()` decorator:

    from betty.app import App
    from betty.cli.commands import command, pass_app

    @command
    @pass_app
    async def my_command(app: App) -> None:
      # Do what your command needs to do here...
      ...

## See also

Read more about how to use the Command Line Interface and Betty’s built-in commands at The command line.