# CLI Recipes

> Ready-to-use Flask CLI commands, covering flask run options and environment variables, flask shell with the app context, flask routes, Flask-Migrate (db init, migrate, upgrade, downgrade), custom click commands registered inside an application factory, and FLASK_APP and .flaskenv setup. Use it for any question about running, inspecting or scripting a Flask app from the terminal, in any language. For the project layout use project-scaffold.

- Skill: `agents-store/cli-recipes-13` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add agents-store/cli-recipes-13`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agents-store/cli-recipes-13/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: agents-store (https://skillmd.com/u/agents-store)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/agents-store/cli-recipes-13

---


# Flask CLI Recipes

Ready-to-use CLI commands for Flask development.

## Running the Application

```bash
# Development server (debug mode: reloader + interactive debugger)
flask --app app run --debug

# Call the factory explicitly (literal arguments are allowed inside the parentheses)
flask --app 'app:create_app()' run --debug

# Specify host and port
flask --app app run --host=0.0.0.0 --port=5001

# Same through environment variables (FLASK_APP, FLASK_DEBUG, FLASK_RUN_PORT)
FLASK_APP=app FLASK_DEBUG=1 flask run

# Extra dotenv file, loaded in addition to .env and .flaskenv
flask --env-file .env.local --app app run
```

`--app` and `--debug` are options of the top-level `flask` command, so they also work for other commands: `flask --app app --debug shell`. Debug mode comes only from `--debug` / `FLASK_DEBUG`; `FLASK_ENV` was removed in Flask 2.3 and is ignored.

## Interactive Shell

```bash
# Start Flask shell with app context
flask shell
```

Inside the shell, the app context is automatically available:

```pycon
>>> from extensions import db
>>> from models import User, Client
>>> db.session.scalars(db.select(User)).all()
>>> db.session.add(User(name='Test', email='test@example.com'))
>>> db.session.commit()
```

## Route Inspection

```bash
# List all registered routes
flask routes

# Output:
# Endpoint         Methods    Rule
# ---------------  ---------  -----------------------
# auth.login       GET, POST  /login
# auth.register    GET, POST  /register
# clients.clients  GET        /clients
# static           GET        /static/<path:filename>
```

`flask routes --sort rule` and `--all-methods` change the ordering and include `HEAD`/`OPTIONS`.

## Database Migrations (Flask-Migrate)

```bash
# Initialize migrations (once)
flask db init

# Create migration after model changes
flask db migrate -m "Add birthday column to clients"

# Apply migrations
flask db upgrade

# Rollback last migration
flask db downgrade

# Show current migration
flask db current

# Show migration history
flask db history
```

## Custom CLI Commands

Register custom commands on `app.cli` (or `blueprint.cli`) with Click decorators. Since Flask 2.2 an app context is already active inside them, so `@with_appcontext` is no longer needed:

```python
# app.py: imports at the top of the file
from datetime import datetime, timedelta

import click

# inside create_app() (the factory pattern has no module-level `app`)
@app.cli.command('seed')
def seed_db():
    """Seed the database with sample data."""
    from extensions import db
    from models import User
    # '!' matches no password: the seeded account cannot sign in until a real hash is set
    user = User(name='Admin', email='admin@example.com', password_hash='!')
    db.session.add(user)
    db.session.commit()
    click.echo('Database seeded.')

@app.cli.command('cleanup')
@click.argument('days', default=30)
def cleanup_old_data(days):
    """Remove records older than N days."""
    cutoff = datetime.now() - timedelta(days=days)
    # ...
    click.echo(f'Cleaned up records older than {days} days.')
```

```bash
flask seed
flask cleanup 60
```

`@with_appcontext` (from `flask.cli`) is still needed for a plain `click.command` that is not registered on `app.cli`, for example one an extension ships through the `flask.commands` entry point; such a command gets no automatic app context.

## Environment Variables

| Variable | Purpose | Default |
|----------|---------|---------|
| `FLASK_APP` | Application module (same as `--app`) | `app.py` or `wsgi.py` |
| `FLASK_DEBUG` | Enable debug mode (same as `--debug`) | `0` |
| `FLASK_RUN_HOST` | Server host | `127.0.0.1` |
| `FLASK_RUN_PORT` | Server port | `5000` |

`FLASK_ENV` is not in this table: it was removed in Flask 2.3 and is ignored. To switch between development, production and test configuration use an application-level variable such as `APP_ENV` (see the `app-patterns` skill).

Use a `.flaskenv` file (with `python-dotenv` installed) for public defaults and `.env` for private values; both are loaded by the `flask` command, and `--env-file` adds another file (`-e path` wins over the defaults):

```bash
# .flaskenv
FLASK_APP=app
APP_ENV=development
FLASK_DEBUG=1
FLASK_RUN_PORT=5001
```

Dotenv files are only read by the `flask` command and `app.run()`. In production (gunicorn, waitress) call `flask.cli.load_dotenv()` yourself or set real environment variables.

## Production Server

```bash
# Gunicorn (Linux/macOS)
pip install gunicorn
gunicorn "app:create_app()" --bind 0.0.0.0:8000 --workers 4

# Waitress (Windows-compatible)
pip install waitress
waitress-serve --call "app:create_app"
```
