Metadata-Version: 2.4
Name: flask-commands
Version: 0.3.8
Summary: A set of command line tools that help you scaffold out your flask application quickly.
License-Expression: MIT
License-File: LICENSE
Author: Drew Butcher
Author-email: drewlbutcher@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: docs
Requires-Dist: Flask (>=3.1,<4)
Requires-Dist: click (>=8.3.1,<9.0.0)
Requires-Dist: pydata-sphinx-theme (>=0.16.1,<0.17.0) ; extra == "docs"
Requires-Dist: python-dotenv (>=1.0,<2)
Requires-Dist: sphinx (<9) ; extra == "docs"
Requires-Dist: sphinx-copybutton ; extra == "docs"
Project-URL: Homepage, https://flask-commands.readthedocs.io/en/latest/
Project-URL: Issues, https://github.com/drewbutcher/flask-commands/issues
Project-URL: Repository, https://github.com/drewbutcher/flask-commands
Description-Content-Type: text/markdown


# <img src="https://raw.githubusercontent.com/drewbutcher/flask-commands/main/docs/source/_static/flask-commands-logo.png" alt="Flask-Commands logo" width="200" style="display:inline-block; vertical-align:middle;"> Flask-Commands


[![pypi](https://img.shields.io/pypi/v/flask-commands.svg?cacheSeconds=300)](https://pypi.org/project/flask-commands/)
[![tests](https://img.shields.io/github/actions/workflow/status/drewbutcher/flask-commands/tests.yml?branch=main)](https://github.com/drewbutcher/flask-commands/actions)
[![coverage](https://codecov.io/gh/drewbutcher/flask-commands/branch/main/graph/badge.svg)](https://codecov.io/gh/drewbutcher/flask-commands)
[![docs](https://img.shields.io/readthedocs/flask-commands/latest)](https://flask-commands.readthedocs.io/)
[![license](https://img.shields.io/pypi/l/flask-commands.svg)](https://github.com/drewbutcher/flask-commands/blob/main/LICENSE)
[![stars](https://img.shields.io/github/stars/drewbutcher/flask-commands)](https://github.com/drewbutcher/flask-commands/stargazers)

**Scaffold Flask apps in seconds.**

**Flask-Commands** is a local-first CLI that scaffolds Flask projects and automates the wiring between views, routes, controllers, and models so you ship faster with consistent structure.

It removes repetitive setup work while keeping every generated file plain, local, and easy to edit.

## Quick video overview

New to Flask-Commands? Start with this short overview:

[![What is Flask-Commands?](https://raw.githubusercontent.com/drewbutcher/flask-commands/main/docs/source/_static/readme-thumbnail.png)](https://youtu.be/lPvQmLLBcwA)

**What is Flask-Commands?**

A quick walkthrough showing how to create a Flask app, generate a CRUD resource, and run it in the browser.

## Getting Started

Flask-Commands bundles opinionated, productivity-focused generators:

- `flask new` boots a ready-to-run Flask project with virtualenv, dotenv, Tailwind wiring, and SQLite + migrations by default. Use `--no-db` to skip DB setup.
- `flask make:view` generates template files and can optionally wire controllers, routes/blueprints, and SQLAlchemy models.
- `flask make:controller` scaffolds a controller class and can optionally add RESTful actions, routes, templates, and model generation (`--model` or `-m`, with `--flat/--nest` for inferred model choices).
- `flask make:model` scaffolds a SQLAlchemy model and can optionally wire RESTful controllers, routes, and templates (`--crud`, with `--flat/--nest` for model structure selection).

All generated code is plain Flask with no hidden runtime layers; every file is created on disk.
The goal is to remove repetitive setup work while keeping everything local and transparent.

## Installation

Flask-Commands is designed to be installed globally so you can create new Flask apps anywhere on your machine.

Recommended:

```bash
pipx install Flask-Commands --include-deps
```

Alternative:

```bash
pip install Flask-Commands
```

You will also want `npm` available because generated Flask projects include Tailwind CSS tooling. If `npm` is not installed, install Node.js first.

## Quick Start

```bash
flask new myproject          # includes a SQLite DB scaffolding by default
cd myproject
```

To create a project without database support, use:

```bash
flask new myproject --no-db
```

Recommended (macOS):

```bash
./run.sh
```

Manual startup:

```bash
source venv/bin/activate
flask run --debug
```

`run.sh` opens a Flask shell, starts the dev server, rebuilds `tailwind.css` and `tailwind.min.css`, opens VS Code and Chrome, and hot-reloads changes in `templates/`, `controllers/`, `forms/`, `models/`, and `routes/`.

Browser reloading uses `fswatch`, so install it first if it is not already available:

```bash
brew install fswatch
```

## Docs quick links

- Quick video overview: https://youtu.be/lPvQmLLBcwA
- Full guide: https://flask-commands.readthedocs.io/en/latest/docs.html
- Install and first run: https://flask-commands.readthedocs.io/en/latest/install_and_first_run.html
- Starting a project: https://flask-commands.readthedocs.io/en/latest/starting_a_project.html
- Core ideas: https://flask-commands.readthedocs.io/en/latest/commands/core_ideas.html
- Cheat sheet: https://flask-commands.readthedocs.io/en/latest/commands/cheat_sheet.html
- Changelog: https://flask-commands.readthedocs.io/en/latest/changelog.html

## Cheat sheet

- `flask new myproject` — New Flask project with DB scaffolding (default).
- `flask new myproject --no-db` — New Flask project without DB setup.
- `flask make:view about` — Template only (`app/templates/about.html`).
- `flask make:view recipes.index -rcm` — Start a recipe resource with a list page, route, controller, and model.
- `flask make:view recipes.show -rc` — Add a detail page to the existing recipe resource.
- `flask make:view recipes.create -rcm` — Add a `GET` action that renders a recipe form template.
- `flask make:view recipes.store -rcm` — Add a `POST` action that wires behavior without creating a template.
- `flask make:view recipes.comments.index -rcm` — Create a nested comments resource under recipes.
- `flask make:controller RecipeController --crud` — Generate RESTful controller methods, routes, and templates for recipes.
- `flask make:controller RecipeController --crud -m` — Generate the RESTful recipe resource and matching model in one controller-first command.
- `flask make:controller ShoppingListController --crud --model ShoppingList` — Keep a multi-word model name together while generating RESTful scaffolding.
- `flask make:controller RecipeIngredientController --crud -m --nest` — Force the nested model interpretation for a controller-first `--crud` flow.
- `flask make:model Recipe` — Create and register a single model scaffold.
- `flask make:model Recipe --crud` — Model + RESTful controller/routes/templates.
- `flask make:model ShoppingList --crud --flat` — Force a flat model interpretation and RESTful structure.
- `flask make:model RecipeIngredient --crud --nest` — Force a nested model interpretation and RESTful structure.


## Examples

Here are a few commands and what they do so you can see the speed,
consistency gains, and how commands combine in practice.

### 1) Create a recipe index page with full wiring

```bash
flask make:view recipes.index -rcm
```

This scaffolds:

- the template at `app/templates/recipes/index.html`
- a controller with an `index` method
- a RESTful route for `/recipes`
- a `Recipe` model plus registration in `app/models/__init__.py`

### 2) Add a recipe detail page to the same resource

```bash
flask make:view recipes.show -rc
```

Because `Recipe` is already registered, route inference generates the RESTful show route:

- `/recipes/<int:recipe_id>`
- the controller method signature includes `recipe_id`


### 3) Generate a full RESTful resource from the controller first

```bash
flask make:controller RecipeController --crud -m
```

This scaffolds the seven RESTful actions across:

- controller methods
- routes in `app/routes/recipes/`
- templates for the `GET` actions (`index`, `show`, `create`, and `edit`)
- a `Recipe` model plus registration

### 4) Handle nested recipe/ingredient model shape intentionally

```bash
flask make:model RecipeIngredient --crud
```

If nested candidates are detected, you will get a prompt to choose flat vs nested.
To skip the prompt explicitly:

```bash
flask make:model RecipeIngredient --crud --flat
flask make:model RecipeIngredient --crud --nest
```

## Contributing

I’m keeping development closed for now, but feedback is welcome.
Please open an issue for bugs or ideas. License: MIT.

