Command Line Interface

Here you can find the documentation about FlaskBB’s Command Line Interface.

To get help for a commands, just type flaskbb COMMAND --help. If no command options or arguments are used it will display all available commands.

Usage: flaskbb [OPTIONS] [COMMAND] [ARGS]...

  This is the commandline interface for flaskbb.

Options:
  --config CONFIG       Specify the config to use either in dotted module
                        notation e.g. 'flaskbb.configs.default.DefaultConfig'
                        or by using a path like '/path/to/flaskbb.cfg'
  --instance PATH       Specify the instance path to use. By default the
                        folder 'instance' next to the package or module is
                        assumed to be the instance path.
  --version             Show the FlaskBB version.
  -e, --env-file FILE   Load environment variables from this file, taking
                        precedence over those set by '.env' and '.flaskenv'.
                        Variables set directly in the environment take
                        highest precedence. python-dotenv must be installed.
  --debug / --no-debug  Set debug mode.
  --help                Show this message and exit.

Commands:
  celery        Preconfigured wrapper around the 'celery' command.
  db            Perform database migrations (Flask-Alembic).
  install       Installs flaskbb.
  makeconfig    Generates a FlaskBB configuration file.
  plugins       Plugins command sub group.
  populate      Creates the necessary tables and groups for FlaskBB.
  reindex       Reindexes the search index.
  routes        Show the routes for the app (Flask's built-in command).
  run           Runs a development server.
  shell         Runs a shell in the app context.
  themes        Themes command sub group.
  translations  Translations command sub group.
  urls          Show routes for the app.
  users         Create, update or delete users.

-e/--env-file and --debug/--no-debug are provided by Flask’s own FlaskGroup - see the Flask CLI documentation for details on those.

Commands

Here you will find a detailed description of every command including all of their options and arguments.

flaskbb install

Installs flaskbb. If no arguments are used, an interactive setup will be run.

--welcome, -w

Disables the generation of the welcome forum.

--force, -f

Doesn’t ask for confirmation if the database should be deleted or not.

--username USERNAME, -u USERNAME

The username of the user.

--email EMAIL, -e EMAIL

The email address of the user.

--password PASSWORD, -p PASSWORD

The password of the user.

--no-plugins, -n

Don’t run the migrations for the default plugins.

flaskbb populate

Creates the necessary tables and groups for FlaskBB.

--test-data, -t

Adds some test data.

--bulk-data, -b

Adds a lot of test data. Combine with --posts and --topics to control how much is generated.

--posts

Number of posts to create in each topic (default: 100).

--topics

Number of topics to create (default: 100).

--force, -f

Will delete the database without asking before populating it.

--initdb, -i

Initializes the database before populating it.

flaskbb run

Runs a local development server (Flask’s built-in run command). This server is for development purposes only - it does not provide the stability, security, or performance of a production WSGI server. See Production & Deployment for how to deploy FlaskBB with gunicorn/uWSGI in production.

--debug, --no-debug

Set debug mode. Enables the reloader and debugger by default.

--host HOST, -h HOST

The interface to bind to.

--port PORT, -p PORT

The port to bind to.

--cert PATH

Specify a certificate file to use HTTPS.

--key FILE

The key file to use when specifying a certificate.

--reload, --no-reload

Enable or disable the reloader. Active by default if debug is enabled.

--debugger, --no-debugger

Enable or disable the debugger. Active by default if debug is enabled.

--with-threads, --without-threads

Enable or disable multithreading.

--extra-files PATH

Extra files that trigger a reload on change. Multiple paths are separated by :.

--exclude-patterns PATH

Files matching these fnmatch patterns will not trigger a reload on change. Multiple patterns are separated by :.

flaskbb serve

Serves FlaskBB with gunicorn. This requires the gunicorn extra to be installed (uv sync --extra gunicorn). Options that are not listed below can be set through a gunicorn configuration file.

--host HOST, -h HOST

The interface to bind FlaskBB to. Defaults to 127.0.0.1.

--port PORT, -p PORT

The port to bind FlaskBB to. Defaults to 8000.

--workers WORKERS, -w WORKERS

The number of worker processes for handling requests. Defaults to 1.

--worker-class CLASS, -k CLASS

The type of worker to use. Defaults to sync.

--daemon, -d

Runs gunicorn in the background.

--gunicorn-config FILE, -c FILE

A gunicorn configuration file. Options given on the command line take precedence over the ones in the configuration file.

flaskbb celery CELERY_ARGS

Starts celery. This is just a preconfigured wrapper around the celery command. Additional arguments are directly passed to celery, e.g. flaskbb celery worker or flaskbb celery beat.

flaskbb shell

Creates a python shell with an app context.

flaskbb urls

Lists all available routes.

--route, -r

Order by route.

--endpoint, -e

Order by endpoint

--methods, -m

Order by methods

flaskbb routes

Flask’s own built-in command for showing all registered routes with their endpoints and methods. Similar to flaskbb urls above, but comes from Flask itself rather than FlaskBB.

--sort [endpoint|methods|domain|rule|match], -s [endpoint|methods|domain|rule|match]

Method to sort routes by. match is the order in which Flask will match routes when dispatching a request.

--all-methods

Show HEAD and OPTIONS methods too.

flaskbb makeconfig

Generates a FlaskBB configuration file.

--development, -d

Creates a development config with DEBUG set to True.

--output, -o

The path where the config file will be saved at. Defaults to the flaskbb’s root folder.

--force, -f

Overwrites any existing config file, if one exsits, WITHOUT asking.

flaskbb reindex

Reindexes the search index.

flaskbb db

Runs database migrations. This sub group is provided by Flask-Alembic and mirrors its CLI 1:1 - see its documentation for the full details of each command. FlaskBB uses alembic’s branching feature so each plugin gets its own migration branch, keyed by the plugin’s name.

revision MESSAGE

Generate a new revision.

--branch NAME, -b NAME

Use this independent branch name, e.g. the plugin’s name, so flaskbb db revision --branch portal "add forum_ids column".

--parent REVISION, -p REVISION

Parent revision(s) of this revision.

--empty

Create an empty script.

--splice

Allow non-head parent revision.

--depend REVISION, -d REVISION

Revision(s) this revision depends on.

--label LABEL, -l LABEL

Label(s) to apply to the revision.

--path PATH

Where to store the revision.

upgrade [TARGET]

Run migrations to upgrade the database. TARGET defaults to heads, which upgrades FlaskBB and every enabled plugin, and can be scoped to a single branch, e.g. flaskbb db upgrade portal@head.

downgrade [TARGET]

Run migrations to downgrade the database, e.g. flaskbb db downgrade portal@base to undo all of a plugin’s migrations.

stamp [TARGET]

Set the current revision without running migrations.

current

Show the list of current revisions.

--check-heads

Check if all head revisions are applied.

heads

Show the list of revisions that have no child revisions.

--resolve-dependencies

Treat dependencies as down revisions.

branches

Show the list of revisions that have more than one next revision.

log

Show the list of revisions in the order they will run.

--start REVISION

Show since this revision.

--end REVISION

Show until this revision.

show [REVISIONS]

Show the given revisions.

merge [REVISIONS]

Generate a merge revision.

--message MESSAGE, -m MESSAGE

The message for the merge revision.

--label LABEL, -l LABEL

Label(s) to apply to the revision.

check

Check if any changes between the database and models are detected.

mkdir

Create the migration directory if it does not exist.

flaskbb translations

Translations command sub group.

new LANG

Adds a new language to FlaskBB’s translations. LANG is the short identifier for the language i.e. ‘en’, ‘de’, ‘de_AT’, etc.

--plugin PLUGIN_NAME, -p PLUGIN_NAME

Adds a new language to a plugin instead of to core.

update

Updates the translations.

--all, -a

Updates all translations, including the ones from the plugins.

--plugin PLUGIN_NAME, -p PLUGIN_NAME

Update the language of the given plugin.

compile

Compiles the translations.

--all, -a

Compiles all translations, including the ones from the plugins.

--plugin PLUGIN_NAME, -p PLUGIN_NAME

Compiles only the given plugin translation.

flaskbb plugins

Plugins command sub group. See Plugins for the full install/uninstall/enable/disable workflow.

new PLUGIN_IDENTIFIER

Creates a new plugin based on the cookiecutter plugin template. Defaults to this template: https://github.com/sh4nks/cookiecutter-flaskbb-plugin. It will either accept a valid path on the filesystem or a URL to a Git repository which contains the cookiecutter template.

--template TEMPLATE, -t TEMPLATE

Path to a cookiecutter template or to a valid git repo.

--out-dir PATH, -o PATH

The location for the new FlaskBB plugin.

--force, -f

Overwrite the contents of the output directory if it exists.

install [PLUGIN_NAME]

Installs a plugin’s settings and applies its migrations (if the plugin has any).

--all, -a

Installs all plugins instead of a single one. Either this or PLUGIN_NAME has to be given.

--settings-only, -s

Only installs the settings.

--migrations-only, -m

Only applies the migrations. Mutually exclusive with --settings-only.

--force, -f

Overwrites existing settings.

uninstall [PLUGIN_NAME]

Uninstalls a plugin’s settings and reverts its migrations (if the plugin has any). Reverting the migrations drops the plugin’s tables, so this asks for confirmation first.

--all, -a

Uninstalls all plugins instead of a single one. Either this or PLUGIN_NAME has to be given.

--settings-only, -s

Only removes the settings. No confirmation is asked for since nothing is dropped.

--migrations-only, -m

Only reverts the migrations. Mutually exclusive with --settings-only.

--force, -f

Doesn’t ask for confirmation.

upgrade [PLUGIN_NAME]

Upgrades a plugin’s settings to match its currently registered SettingGroup and applies its newest migrations - use this after upgrading a plugin whose settings or database schema changed between versions.

--all, -a

Upgrades all plugins instead of a single one. Either this or PLUGIN_NAME has to be given.

--settings-only, -s

Only upgrades the settings.

--migrations-only, -m

Only applies the migrations. Mutually exclusive with --settings-only.

enable PLUGIN_NAME

Enables a plugin.

disable PLUGIN_NAME

Disables a plugin.

list

Lists all installed plugins.

cleanup

Removes zombie plugins from FlaskBB - a zombie plugin is one that has a row in the database but is no longer installed in the environment.

flaskbb themes

Themes command sub group.

new THEME_IDENTIFIER

Creates a new theme based on the cookiecutter theme template. Defaults to this template: https://github.com/sh4nks/cookiecutter-flaskbb-theme. It will either accept a valid path on the filesystem or a URL to a Git repository which contains the cookiecutter template.

--template TEMPLATE, -t TEMPLATE

Path to a cookiecutter template or to a valid git repo.

--out-dir PATH, -o PATH

The location for the new FlaskBB theme.

--force, -f

Overwrite the contents of the output directory if it exists.

remove THEME_IDENTIFIER

Removes a theme from the filesystem by the theme’s identifier.

--force, -f

Removes the theme without asking for confirmation first.

list

Lists all installed themes.

flaskbb users

Create, update or delete users. Omit an option to be prompted for it interactively.

new

Creates a new user.

--username USERNAME, -u USERNAME

The username of the user.

--email EMAIL, -e EMAIL

The email address of the user.

--password PASSWORD, -p PASSWORD

The password of the user.

--group GROUP, -g GROUP

The primary group of the user. The group GROUP has to be one of admin, super_mod, mod or member.

update

Updates an user.

--username USERNAME, -u USERNAME

The username of the user.

--email EMAIL, -e EMAIL

The email address of the user.

--password PASSWORD, -p PASSWORD

The password of the user.

--group GROUP, -g GROUP

The primary group of the user. The group GROUP has to be one of admin, super_mod, mod or member.

delete

Deletes a user.

--username USERNAME, -u USERNAME

The username of the user.

--force, -f

Removes the user without asking for confirmation first.