How to set a help message for a Flask command group?

Question

I'm trying to adapt an example from Flask documentation to create a custom command in a group:

import click
from flask import Flask
from flask.cli import AppGroup

app = Flask(__name__)
user_cli = AppGroup('user')

@user_cli.command('create')
@click.argument('name')
def create_user(name):
    ...

app.cli.add_command(user_cli)

$ flask user create demo

This appears to work fine, however when I run flask --help I see the commands listed without any help messages, e.g.:

Commands:
  user
  foo
  db             Perform database migrations.

How can I add a help message to a group of commands ('user' in this case)?

Answer 1

Use the short_help parameter. AppGroup inherits from Group which inherits from MultiCommand which inherits from Command. See Click source code for Command.

For example:

import click
from flask import Flask
from flask.cli import AppGroup

user_cli = AppGroup('user', short_help="Adds a user")


@user_cli.command('create')
@click.argument('name')
def create_user(name):
    print(name)


app = Flask(__name__)

app.cli.add_command(user_cli)

@app.route('/')
def hello_world():
    return 'Hello World!'


if __name__ == '__main__':
    app.run()

Gives the following output (Windows PyCharm terminal):

(flask_cli_group) D:\Paul\PycharmProjects\flask_cli_group>flask
Usage: flask [OPTIONS] COMMAND [ARGS]...

  A general utility script for Flask applications.

  Provides commands from Flask, extensions, and the application. Loads the
  application defined in the FLASK_APP environment variable, or from a
  wsgi.py file. Setting the FLASK_ENV environment variable to 'development'
  will enable debug mode.

    > set FLASK_APP=hello.py
    > set FLASK_ENV=development
    > flask run

Options:
  --version  Show the flask version
  --help     Show this message and exit.

Commands:
  routes  Show the routes for the app.
  run     Run a development server.
  shell   Run a shell in the app context.
  user    Adds a user

(flask_cli_group) D:\Paul\PycharmProjects\flask_cli_group>

Answer 2

If you use a Blueprint to create CLI commands, add blueprint_obj.cli.short_help for top-level help:

bp_database = Blueprint('bp_database', __name__, cli_group='database')
bp_database.cli.short_help = 'Database utilities'

Output:

Commands:
  database  Database utilities
  run       Run a development server.
  shell     Run a shell in the app context.