# Gemini CLI with Flask: Practical Developer Workflow

URL: https://agentvera.dev/en/blog/gemini-cli-for-flask/ · Published: 2026-11-01

Use Gemini CLI on Flask projects: set up GEMINI.md, write prompts for blueprints, SQLAlchemy, Jinja and pytest, and avoid Flask-specific pitfalls.

**In short:**

- Set up a project-level GEMINI.md with Flask commands, blueprint rules, and url_for conventions before prompting Gemini CLI.
- Ask for one small change at a time, then run pytest and ruff and review the git diff for Flask-specific mistakes.
- Watch for direct app routes, hardcoded URLs, lazy SQLAlchemy loads, and Jinja logic when Gemini CLI edits Flask files.

Gemini CLI works well on Flask projects because it operates in the same project directory as your application factory, blueprints, templates, and tests. You can guide it with a project-level GEMINI.md, ask for small changes, run pytest after each turn, and review the diff. This guide covers the setup, prompts, verification, and pitfalls specific to Flask. [Gemini CLI](/en/agents/gemini-cli/)

## Why Gemini CLI fits Flask’s blueprint and factory structure

Flask applications are mostly plain Python plus Jinja templates, which means Gemini CLI can read the exact request flow from route decorators to template rendering. It can inspect how blueprints are registered in create_app, follow imports between models and views, and run the same commands you use: `python -m pytest`, `ruff check .`, and `python -m flask --app run.py routes`. This makes it useful for refactoring a route, adding a SQLAlchemy query, or updating a Jinja template without needing a separate browser tool. Because Flask projects are often structured around small units like blueprints, Gemini CLI can make one blueprint change and verify it with focused tests.

## Project setup: GEMINI.md for Flask commands and conventions

Put a GEMINI.md file at the repository root. Gemini CLI reads this file before acting, so it is the most reliable way to keep the agent aligned with your Flask conventions. Keep it short and command-focused; do not paste entire documentation. Include build, test, lint, run commands, folder layout, and rules that prevent common Flask mistakes. For a typical application factory project with blueprints and SQLAlchemy, a useful GEMINI.md looks like this:

```markdown
## Commands
- Install: python -m pip install -e '.[dev]'
- Test: python -m pytest -q
- Lint: ruff check .
- Run dev server: python -m flask --app run.py run --debug

## Layout
- app/ contains create_app() and extensions
- app/blueprints/ holds one blueprint package per feature
- app/templates/<blueprint>/ holds that blueprint's Jinja files
- app/models.py contains all SQLAlchemy models
- tests/ mirrors app/ with test_*.py files

## Flask rules
- All routes must be registered inside blueprints, not directly on app
- Use url_for, never hardcode URL paths
- Models live in app/models.py; no lazy loading after session close
- Templates must not run queries or business logic
- app context and request context must not be used at import time
```

Replace commands with the exact ones for your package manager and test runner. The important part is that every convention a new contractor would need is written down. When in doubt, add a rule for the mistake you do not want to see.

## A practical loop: plan, edit, test, review

Treat Gemini CLI like a fast junior engineer: give it a clear, small task, then inspect the diff and run the tests yourself. Do not ask it to build a whole feature in one turn. A reliable loop follows [AI pair programming](/en/blog/ai-pair-programming/) principles: plan the change, edit one area, run focused tests, review the diff, then commit or ask for the next step.

Example prompts for typical Flask tasks:

- Read the auth blueprint and list all its routes and their endpoint names. Then propose a new password reset endpoint that matches the existing conventions.
- Add a `last_seen` datetime column to the User model in app/models.py. Update the profile blueprint and its template to show the value. Do not create a migration yet.
- In tests/test_orders.py, add a session-scoped app fixture and a client fixture. Then add two tests: the order detail route returns 200 for the owner and 403 for another logged-in user.
- Refactor the duplicate order query in the dashboard blueprint into a helper in app/services.py. Update the dashboard view to pass the result through context.
- Run python -m pytest -q. Fix any failures you introduced. Show me the git diff as a unified patch and summarize the files changed.

After each prompt, run the relevant test file, then the whole suite. Keep changes small enough that `git diff` remains reviewable in under a minute.

## Flask tasks the agent handles well and pitfalls to watch

Gemini CLI handles many Flask changes well: registering new blueprints in create_app, adding route handlers, adjusting Jinja templates, writing SQLAlchemy queries, and expanding pytest coverage. The areas that need close review are the Flask-specific edges.

| Flask area | What to ask for | What to check after the edit |
| --- | --- | --- |
| Blueprint registration | Add a new settings blueprint and register it with the url_prefix /settings | Confirm it registers in create_app and uses the project’s blueprint package layout, not a single file with `Blueprint` defined inline |
| URL building | Update this template link to the profile endpoint | Ensure `url_for('profile.index', user_id=user.id)` has the blueprint name, not just `url_for('profile')` |
| SQLAlchemy models | Add a relationship between Post and Comment | Check for lazy loading after the session is gone; add `selectinload` or join where needed |
| Jinja templates | Show the order total and status in the list | Ensure the template receives variables from the view, not queries; keep logic in Python |
| pytest fixtures | Create a fixture for an app with the test database | Confirm the fixture yields app context or request context and rolls back data between tests |

Common pitfalls to correct immediately:

- The agent adds `@app.route` directly inside create_app or at module level instead of using the blueprint specified in GEMINI.md.
- It uses `url_for('dashboard')` when the blueprint endpoint is `dashboard.index`.
- It imports `current_app` or `request` at module import time, which works only inside an application context or request context.
- It produces SQLAlchemy relationships that trigger lazy loads after the session has been closed, giving `DetachedInstanceError`.
- It puts query-building or conditional business logic into Jinja templates because the prompt was phrased as make the template show active orders.
- It tries to run database migrations or `flask db upgrade` without being asked, or writes migration code by hand when your project uses Alembic autogenerate.

When you spot one of these, add a rule to GEMINI.md and ask it to fix the specific file. This is faster than re-explaining the same convention in every prompt.

## Testing and verifying Flask changes with the agent

Verification is not optional. For Flask changes, run:

- `python -m pytest -q` after every code change; if the change touches one blueprint, run `python -m pytest tests/test_auth.py -q` first.
- `ruff check .` to catch unused imports in blueprint files.
- `python -m flask --app run.py routes` to confirm a new route is registered under the expected endpoint and URL rule.
- Start the dev server and manually hit the affected URLs when the change involves templates, forms, or redirects.

Ask Gemini CLI to run the tests itself after a change, but do not trust its summary alone. Open the diff and look at the routes, url_for calls, and SQLAlchemy session usage. If a test fails, ask it to [debug code with AI](/en/blog/debug-code-with-ai/) by reading the traceback and the fixture setup rather than replacing a test with a weaker assertion.

## Parallel agents on a Flask project with AgentVera

For larger Flask work, you can split tasks by blueprint or layer: one agent may add authentication while another works on the order list. AgentVera runs the real Gemini CLI in separate terminal panels and can place each agent in its own git worktree, so parallel changes do not overwrite each other. After each agent turn, automatic code review checks for Flask issues like broken `url_for` calls or unregistered blueprints, and checkpoints let you undo a change that breaks the application factory. This [AI agent orchestration](/en/blog/ai-coding-agent-orchestration/) fits a modular Flask codebase well.

## Wrap-up

Gemini CLI is most effective on Flask projects when you treat it as a code-aware teammate: put your conventions in GEMINI.md, ask for one focused change at a time, run pytest and ruff after every turn, and review the diff for Flask-specific mistakes. The loop may feel slower at first, but it prevents the common failure mode of an agent generating a large patch that breaks the application factory or template rendering. Use focused prompts, keep blueprints and url_for rules explicit, and the agent will handle many day-to-day Flask tasks cleanly.

## Frequently asked questions

**How do I start Gemini CLI in a Flask project?** Run gemini from the project root after creating a GEMINI.md file with your Flask commands and conventions. Start with a small, focused prompt such as reading a blueprint or adding a single route, then review the diff and run pytest.

**What should I put in GEMINI.md for a Flask app?** Include install, test, lint, and run commands, the folder layout for app, blueprints, templates and tests, and rules like register routes only via blueprints, use url_for, and avoid lazy SQLAlchemy loads after session close.

**Can Gemini CLI modify Flask blueprints safely?** Yes, if you state the blueprint conventions clearly and ask for one change at a time. Check that it registers the blueprint in create_app and uses the correct endpoint names in url_for calls; it may otherwise add app.route directly or hardcode URLs.

**How do I test changes Gemini CLI makes to Flask routes and models?** Run python -m pytest -q after each turn, run python -m flask --app run.py routes to verify new endpoints, and run ruff check . for unused imports. For template and form changes, start the dev server and manually exercise the affected URLs.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/