CLI & Shell

import os
import pathlib
import subprocess
import sys
import tempfile

root = pathlib.Path(tempfile.mkdtemp())
CLEAN_ENV = {k: v for k, v in os.environ.items() if not k.startswith("FLASK_")}


def project(name, files):
    """Create a throwaway project directory and return it."""
    directory = root / name
    directory.mkdir(parents=True, exist_ok=True)
    for filename, body in files.items():
        path = directory / filename
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(body)
    return directory


def flask(*args, cwd, env=None, input=None):
    result = subprocess.run(
        [sys.executable, "-m", "flask", *args],
        cwd=cwd,
        env={**CLEAN_ENV, **(env or {})},
        input=input,
        capture_output=True,
        text=True,
        timeout=60,
    )
    return result.returncode, (result.stdout + result.stderr).strip()


APP = "from flask import Flask\napp = Flask(__name__)\n\n@app.get('/{path}')\ndef view():\n    return 'ok'\n"

both = project("both", {"wsgi.py": APP.format(path="from-wsgi"), "app.py": APP.format(path="from-app")})
code, out = flask("routes", cwd=both)  # no --app: wsgi.py is tried before app.py
assert code == 0 and "/from-wsgi" in out and "/from-app" not in out
print(out)

two = project("two", {"pair.py": "from flask import Flask\nfirst = Flask('a')\nsecond = Flask('b')\n"})
code, out = flask("--app", "pair", "routes", cwd=two)  # two instances: ambiguous
assert code != 0
print(out.splitlines()[-1])
code, out = flask("--app", "pair:second", "routes", cwd=two)  # module:name settles it
assert code == 0

broken = project("broken", {"shop.py": "import package_that_does_not_exist\n"})
code, out = flask("--app", "shop", "routes", cwd=broken)  # an ImportError inside the module is reported as such
assert code != 0 and "ImportError" in out
print(next(line for line in out.splitlines() if line.startswith("Error:")))

src = project("src_layout", {"src/hello.py": APP.format(path="hello")})
code, out = flask("--app", "src/hello", "routes", cwd=src)  # the directory goes on sys.path
assert code == 0 and "/hello" in out
code, out = flask("routes", cwd=src, env={"FLASK_APP": "src/hello"})  # FLASK_APP takes the same value
assert code == 0 and "/hello" in out

Endpoint  Methods  Rule
--------  -------  -----------------------
static    GET      /static/<path:filename>
view      GET      /from-wsgi
Error: Detected multiple Flask applications in module 'pair'. Use 'pair:name' to specify the correct one.
Error: While importing 'shop', an ImportError was raised:

factory = project(
    "factory",
    {
        "bookshelf.py": (
            "from flask import Flask\n"
            "\n"
            "def create_app(config_name='default', *, title='Bookshelf'):\n"
            "    app = Flask(__name__)\n"
            "    app.config['TITLE'] = title\n"
            "    app.add_url_rule(f'/{config_name}', 'index', lambda: title)\n"
            "    return app\n"
        )
    },
)
code, out = flask("--app", "bookshelf", "routes", cwd=factory)  # defaults for every parameter: auto-detected
assert code == 0 and "/default" in out
code, out = flask("--app", 'bookshelf:create_app("dev", title="Dev Shelf")', "routes", cwd=factory)
assert code == 0 and "/dev" in out
print(out)
code, out = flask("--app", "bookshelf:create_app(title=len)", "routes", cwd=factory)  # not a literal
assert code != 0
print(out.splitlines()[-1])

Endpoint  Methods  Rule
--------  -------  -----------------------
index     GET      /dev
static    GET      /static/<path:filename>
Error: Failed to parse arguments as literal values: 'create_app(title=len)'.

envdemo = project(
    "envdemo",
    {
        "shelf.py": (
            "import os\n"
            "import click\n"
            "from flask import Flask\n"
            "\n"
            "app = Flask(__name__)\n"
            "\n"
            "@app.cli.command('where')\n"
            "def where():\n"
            "    click.echo(os.environ.get('BOOKSHELF_MODE', 'unset'))\n"
        ),
        ".flaskenv": "\n".join(["FLASK_APP=shelf", "BOOKSHELF_MODE=from-flaskenv", ""]),
        ".env": "BOOKSHELF_MODE=from-dotenv\n",
        "staging.env": "BOOKSHELF_MODE=from-env-file\n",
    },
)
modes = {}
modes["files"] = flask("where", cwd=envdemo)[1]  # no --app needed: .flaskenv sets FLASK_APP
modes["env-file"] = flask("--env-file", "staging.env", "where", cwd=envdemo)[1]
modes["process"] = flask("--env-file", "staging.env", "where", cwd=envdemo, env={"BOOKSHELF_MODE": "from-process"})[1]
modes["skip"] = flask("--app", "shelf", "where", cwd=envdemo, env={"FLASK_SKIP_DOTENV": "1"})[1]
assert modes == {
    "files": "from-dotenv",
    "env-file": "from-env-file",
    "process": "from-process",
    "skip": "unset",
}
print(modes)

{'files': 'from-dotenv', 'env-file': 'from-env-file', 'process': 'from-process', 'skip': 'unset'}

import socket
import time
import urllib.request

server = project(
    "server",
    {"hello.py": "from flask import Flask\napp = Flask(__name__)\n\n@app.get('/')\ndef index():\n    return 'Bookshelf is up'\n"},
)


def free_port():
    with socket.socket() as sock:
        sock.bind(("127.0.0.1", 0))
        return sock.getsockname()[1]


def serve_and_get(args, env=None, port=None):
    port = port or free_port()
    process = subprocess.Popen(
        [sys.executable, "-m", "flask", *args(port)],
        cwd=server,
        env={**CLEAN_ENV, **(env or {})},
        stdout=subprocess.DEVNULL,
        stderr=subprocess.DEVNULL,
    )
    try:
        for _ in range(100):
            try:
                with urllib.request.urlopen(f"http://127.0.0.1:{port}/", timeout=2) as response:
                    return response.status, response.read().decode()
            except OSError:
                time.sleep(0.1)
        raise RuntimeError("the server did not start")
    finally:
        process.terminate()
        process.wait(timeout=10)


# the option form
print(serve_and_get(lambda port: ["--app", "hello", "run", "--port", str(port), "--host", "127.0.0.1"]))

# the environment form: no --port on the command line
port = free_port()
print(serve_and_get(lambda _: ["--app", "hello", "run"], env={"FLASK_RUN_PORT": str(port)}, port=port))

(200, 'Bookshelf is up')
(200, 'Bookshelf is up')

from flask import Blueprint, Flask
from flask.cli import FlaskGroup

shelf = Flask("bookshelf", subdomain_matching=True)
shelf.config["SERVER_NAME"] = "bookshelf.test"
api = Blueprint("api", __name__, url_prefix="/api", subdomain="api")


@shelf.get("/books/<int:book_id>")
def book_detail(book_id):
    return str(book_id)


@shelf.get("/books/new")
def book_form():
    return "form"


@api.get("/books")
def book_list():
    return "[]"


shelf.register_blueprint(api)
cli = FlaskGroup(create_app=lambda: shelf)  # the built-in commands are reachable through a FlaskGroup
runner = shelf.test_cli_runner()
result = runner.invoke(cli, ["routes", "--sort", "match"])
assert result.exit_code == 0, result.output
print(result.output)
assert shelf.test_client().get("/books/new").data == b"form"  # static parts beat converters, whatever the listing order

Endpoint       Methods  Subdomain  Rule
-------------  -------  ---------  -----------------------
static         GET                 /static/<path:filename>
book_detail    GET                 /books/<int:book_id>
book_form      GET                 /books/new
api.book_list  GET      api        /api/books

Python 3.13.15 (main, Aug 25 2026, 13:50:12) [Clang 22.1.3 ] on darwin
App: bookshelf
Instance: /home/ana/bookshelf/instance
>>>

import secrets

shell_app_dir = project(
    "shellapp",
    {
        "shelfshell.py": (
            "from flask import Flask, current_app\n"
            "\n"
            "class Book:\n"
            "    def __init__(self, title):\n"
            "        self.title = title\n"
            "\n"
            "def create_app():\n"
            "    app = Flask(__name__)\n"
            "    app.config['PAGE_SIZE'] = 10\n"
            "\n"
            "    @app.shell_context_processor\n"
            "    def add_names():\n"
            "        return {'Book': Book, 'page_size': current_app.config['PAGE_SIZE']}\n"
            "\n"
            "    return app\n"
        )
    },
)

# What the shell will contain, without starting it
sys.path.insert(0, str(shell_app_dir))
import shelfshell

shell_app = shelfshell.create_app()
with shell_app.app_context():  # the flask shell command pushes this context for you
    namespace = shell_app.make_shell_context()
assert set(namespace) == {"app", "g", "Book", "page_size"}
print(sorted(namespace))

# And the real command, with a script on standard input instead of a terminal
script = "print(Book('Dune').title, page_size, app.name)\n"
code, out = flask("--app", "shelfshell", "shell", cwd=shell_app_dir, input=script)
assert code == 0 and "Dune 10 shelfshell" in out
print(next(line for line in out.splitlines() if "Dune" in line))

['Book', 'app', 'g', 'page_size']
>>> Dune 10 shelfshell

from flask import Flask, g, request, url_for

demo = Flask("shell-demo")


@demo.before_request
def load_current_user():
    g.user = "ana"


@demo.get("/books/<int:book_id>", endpoint="book")
def book(book_id):
    return str(book_id)


ctx = demo.test_request_context("/books/7?page=2")
ctx.push()
try:
    demo.preprocess_request()  # runs before_request functions, like a real request would
    print(request.path, request.args["page"], g.user, url_for("book", book_id=7))
finally:
    ctx.pop()  # pops the context and runs the teardown functions

/books/7 2 ana /books/7

import json
import sqlite3

import click
from flask import Flask, current_app, g


def get_db():
    if "db" not in g:
        g.db = sqlite3.connect(current_app.config["DATABASE"])
        g.db.execute("CREATE TABLE IF NOT EXISTS book (title TEXT PRIMARY KEY, author TEXT, year INTEGER)")
    return g.db


def create_app(database):
    app = Flask("bookshelf")
    app.config["DATABASE"] = database

    @app.teardown_appcontext
    def close_db(exception):
        db = g.pop("db", None)
        if db is not None:
            db.close()

    @app.cli.command("add-book")
    @click.argument("title")
    @click.option("--author", required=True, help="Name of the author.")
    @click.option("--year", type=click.IntRange(min=1000, max=2100), default=2000, show_default=True)
    def add_book(title, author, year):
        """Add one book to the catalogue."""
        db = get_db()
        try:
            db.execute("INSERT INTO book VALUES (?, ?, ?)", (title, author, year))
        except sqlite3.IntegrityError:
            raise click.ClickException(f"{title!r} is already in the catalogue") from None
        db.commit()
        click.echo(f"Added {title!r} ({year})")

    @app.cli.command("count-books")
    @click.option("--as-json", is_flag=True, help="Print JSON instead of text.")
    def count_books(as_json):
        """Print the number of books."""
        total = get_db().execute("SELECT COUNT(*) FROM book").fetchone()[0]
        click.echo(json.dumps({"books": total}) if as_json else f"{total} books")

    return app


cmd_app = create_app(str(root / "commands.db"))
runner = cmd_app.test_cli_runner()

result = runner.invoke(args=["add-book", "Dune", "--author", "Frank Herbert", "--year", "1965"])
assert result.exit_code == 0 and result.output == "Added 'Dune' (1965)\n"
print(result.output.strip())

result = runner.invoke(args=["add-book", "Dune", "--author", "Frank Herbert"])  # duplicate: ClickException
assert result.exit_code == 1
print(result.output.strip())

result = runner.invoke(args=["add-book", "Emma", "--author", "Jane Austen", "--year", "3000"])  # outside the range
assert result.exit_code == 2
print(result.output.splitlines()[-1])

assert runner.invoke(args=["count-books", "--as-json"]).output == '{"books": 1}\n'
print(runner.invoke(args=["add-book", "--help"]).output)

Added 'Dune' (1965)
Error: 'Dune' is already in the catalogue
Error: Invalid value for '--year': 3000 is not in the range 1000<=x<=2100.
Usage: bookshelf add-book [OPTIONS] TITLE

  Add one book to the catalogue.

Options:
  --author TEXT         Name of the author.  [required]
  --year INTEGER RANGE  [default: 2000; 1000<=x<=2100]
  --help                Show this message and exit.

env_project = project(
    "envopts",
    {
        "shelf.py": (
            "import click\n"
            "from flask import Flask\n"
            "from flask.cli import AppGroup\n"
            "\n"
            "app = Flask(__name__)\n"
            "books = AppGroup('books')\n"
            "\n"
            "@books.command('purge')\n"
            "@click.option('--older-than', type=int, default=30)\n"
            "def purge(older_than):\n"
            "    click.echo(f'older-than={older_than}')\n"
            "\n"
            "@app.cli.command('page')\n"
            "@click.option('--size', type=int, default=10, envvar='BOOKSHELF_PAGE_SIZE')\n"
            "def page(size):\n"
            "    click.echo(f'size={size}')\n"
            "\n"
            "app.cli.add_command(books)\n"
        )
    },
)
assert flask("--app", "shelf", "books", "purge", cwd=env_project)[1] == "older-than=30"
assert flask("--app", "shelf", "books", "purge", cwd=env_project, env={"FLASK_BOOKS_PURGE_OLDER_THAN": "90"})[1] == "older-than=90"
assert flask("--app", "shelf", "books", "purge", "--older-than", "7", cwd=env_project, env={"FLASK_BOOKS_PURGE_OLDER_THAN": "90"})[1] == "older-than=7"
assert flask("--app", "shelf", "page", cwd=env_project, env={"BOOKSHELF_PAGE_SIZE": "25"})[1] == "size=25"

[project.entry-points."flask.commands"]
bookshelf-doctor = "bookshelf_tools.commands:doctor"

# bookshelf_tools/commands.py
import click


@click.command()
def doctor():
    """Check the Bookshelf environment."""
    click.echo("all good")

plugin_dir = root / "plugin_site"
(plugin_dir / "bookshelf_tools").mkdir(parents=True)
(plugin_dir / "bookshelf_tools" / "__init__.py").write_text("")
(plugin_dir / "bookshelf_tools" / "commands.py").write_text(
    "import click\n\n@click.command()\ndef doctor():\n    \"\"\"Check the Bookshelf environment.\"\"\"\n    click.echo('all good')\n"
)
dist_info = plugin_dir / "bookshelf_tools-0.1.dist-info"
dist_info.mkdir()
(dist_info / "METADATA").write_text("Metadata-Version: 2.1\nName: bookshelf-tools\nVersion: 0.1\n")
(dist_info / "entry_points.txt").write_text("[flask.commands]\nbookshelf-doctor = bookshelf_tools.commands:doctor\n")

nowhere = project("nowhere", {})  # a directory with no application at all
code, out = flask("bookshelf-doctor", cwd=nowhere, env={"PYTHONPATH": str(plugin_dir)})
assert code == 0 and out == "all good"
print(out)
code, out = flask("--help", cwd=nowhere, env={"PYTHONPATH": str(plugin_dir)})
assert "bookshelf-doctor" in out

all good

from click.testing import CliRunner
from flask.cli import FlaskGroup


def make_bookshelf():
    app = Flask("bookshelf")

    @app.cli.command("seed")
    def seed():
        """Seed the catalogue."""
        click.echo(f"seeding {current_app.name}")

    return app


@click.group(cls=FlaskGroup, create_app=make_bookshelf, add_version_option=False, load_dotenv=False)
def bookshelf():
    """Management script for the Bookshelf."""


@bookshelf.command()
def about():
    """Prints a line; has no application context."""
    click.echo("Bookshelf management script")


runner = CliRunner()
result = runner.invoke(bookshelf, ["about"])
assert result.output == "Bookshelf management script\n"
result = runner.invoke(bookshelf, ["seed"])
assert result.output == "seeding bookshelf\n"
result = runner.invoke(bookshelf, ["--help"])
print("\n".join(line for line in result.output.splitlines() if line.startswith("  ") and line.split()[0] in {"about", "seed", "routes", "run", "shell"}))


@click.group()
def ops():
    """Umbrella script."""


ops.add_command(bookshelf, "shelf")  # FlaskGroup as a sub-command of another group
assert runner.invoke(ops, ["shelf", "seed"]).output == "seeding bookshelf\n"

  about    Prints a line; has no application context.
  routes   Show the routes for the app.
  run      Run a development server.
  seed     Seed the catalogue.
  shell    Run a shell in the app context.

[project.scripts]
bookshelf = "bookshelf.cli:bookshelf"

pip install -e .
bookshelf run --debug
bookshelf seed

import pytest


@pytest.fixture
def app(tmp_path):
    app = create_app(str(tmp_path / "test.db"))
    app.config.update(TESTING=True)
    return app


@pytest.fixture
def runner(app):
    return app.test_cli_runner()


def test_add_book_and_count(runner):
    result = runner.invoke(args=["add-book", "Emma", "--author", "Jane Austen"])
    assert result.exit_code == 0
    assert "Added 'Emma'" in result.output
    assert runner.invoke(args=["count-books"]).output == "1 books\n"


def test_missing_author_is_a_usage_error(runner):
    result = runner.invoke(args=["add-book", "Emma"])
    assert result.exit_code == 2
    assert "--author" in result.output


def test_usage_errors_are_exit_codes(runner):
    result = runner.invoke(args=["add-book"], catch_exceptions=False)
    assert result.exit_code == 2  # usage errors are not exceptions: Click turns them into an exit code


# a minimal pytest-free run of the same tests, so that the block is self-checking
import tempfile

for test in (test_add_book_and_count, test_missing_author_is_a_usage_error, test_usage_errors_are_exit_codes):
    scratch = pathlib.Path(tempfile.mkdtemp())
    test(create_app(str(scratch / "test.db")).test_cli_runner())
print("3 passed")

3 passed

flask --app bookshelf books purge --yes

{
    "name": "Flask: Bookshelf",
    "type": "debugpy",
    "request": "launch",
    "module": "flask",
    "env": {
        "FLASK_APP": "bookshelf",
        "FLASK_DEBUG": "1"
    },
    "args": ["run", "--no-debugger", "--no-reload"],
    "jinja": true,
    "justMyCode": true
}