Gemini CLI is a terminal coding agent that can read your whole FastAPI repository and make coordinated changes across routers, schemas, dependencies, and tests. Start it with gemini in the project folder, keep a concise GEMINI.md at the repository root, and use the loop below to keep changes reviewable. This guide focuses on realistic FastAPI workflows: path operations, Pydantic models, dependency injection, async endpoints, and pytest with TestClient.
Why Gemini CLI fits FastAPI development
FastAPI projects have a predictable shape: an app factory or main module, routers, Pydantic schemas, and dependency functions. Gemini CLI is effective here because it can hold that structure in context while editing multiple files at once. For example, changing a response model often means updating a schema, a router import, a service return type, and a test expectation; the agent can do all four in one small diff.
It also handles the repetitive parts well: adding standard error responses, converting sync handlers to async def where I/O is involved, and writing parametrized pytest cases. The value is not in generating code from scratch, but in making small, verified increments across a codebase that already has conventions. Keep tasks narrow so the agent does not refactor unrelated code or introduce circular imports.
Preparing the project: what to put in GEMINI.md
The most important file is GEMINI.md at the repository root. It tells the agent how to build, test, lint, and where code lives. For FastAPI, include explicit rules that prevent the most common mistakes. A realistic minimal file:
# GEMINI.md
Project: FastAPI service for user and order management.
Commands:
- install: python -m pip install -e ".[dev]"
- test: python -m pytest -q
- lint: python -m ruff check app tests
- run: uvicorn app.main:app --reload
Layout:
- app/main.py: create FastAPI instance and include routers.
- app/routers/: path operations only, no business logic.
- app/schemas.py: Pydantic v2 models for requests and responses.
- app/deps.py: dependency injection functions.
- app/services.py: business logic.
- tests/: pytest files using TestClient.
Rules:
- Use async def for endpoints that perform I/O; use sync def only for pure CPU work.
- Always set response_model on decorators unless returning a Response object.
- Use Pydantic v2 syntax: model_validate, model_dump, field_validator.
- Dependencies are functions, not classes, and are imported from app.deps.
- Never create a new router without registering it in app.main.
- Before declaring a task done, run pytest and ruff and show the output.Keep the file short enough that the agent does not ignore it. Update it when you add a new router or change test commands. For more on the general workflow, see How to use Gemini CLI: a step-by-step guide.
A repeatable workflow: plan, edit, test, review
Treat the agent as a junior FastAPI developer with strong Python skills but no memory between sessions. Use this loop:
- Plan: name the endpoint, schema, or bug and the files that should change.
- Small step: ask for one coherent change, not a feature branch.
- Run tests: tell the agent to run
python -m pytest -qandpython -m ruff check app testsafter the edit. - Review the diff: look at imports, dependency injection, and response_model before merging.
- Iterate: feed any failure or review comment back to the agent.
Example prompts that work well for FastAPI tasks:
- Add a
GET /users/{user_id}endpoint that returnsUserOutand raises 404 when missing. Put the route inapp/routers/users.pyand add a pytest withTestClient. - Create a
create_orderPydantic schema and arequire_api_keydependency. Use them in an asyncPOST /ordersendpoint, and write tests for missing and invalid API keys. - Refactor the existing orders router to call functions from
app/services.pyinstead of doing database work inline. Keep the public response shape unchanged and update tests only where necessary. - Fix the failing test in
tests/test_auth.pywithout changing the public API. Explain the dependency injection error before editing. - Add a
GET /healthendpoint that returns{"status":"ok"}only after a startup check for the database, and test both healthy and unhealthy states.
Where Gemini CLI excels in FastAPI and where it stumbles
Gemini CLI is strong at adding standard CRUD endpoints, converting payloads between Pydantic schemas and ORM objects, and writing table-driven tests. It is less reliable when it has to guess project-specific conventions or when a change touches many routers at once.
| Task | Good prompt | Watch closely |
|---|---|---|
| Add a JSON POST endpoint | Add POST /items with ItemCreate and ItemOut, async def, response_model=ItemOut. | It may skip response_model or use sync def and block the event loop. |
| Add dependency injection | Add get_current_user from app.deps and require it on the profile route. | It may create circular imports between routers and deps, or use Depends in a non-route helper. |
| Pydantic validation | Add a field_validator to normalize emails before storing. | It may use Pydantic v1 decorators like @validator or call .dict() instead of model_dump(). |
| Test a route | Write a pytest for PATCH /users/{user_id} using TestClient and dependency_overrides. | It may overmock dependencies and not test status codes or response shape; it may also forget to restore overrides. |
Review any new dependency injection because a wrong Depends signature often passes tests but fails at runtime. Watch for sync endpoints that call await or async endpoints that call blocking I/O without run_in_threadpool. If a change touches Pydantic schemas, run a quick check that all response_model imports still resolve before accepting the diff.
Testing FastAPI changes with the agent
Require the agent to run the test suite after every change. Use python -m pytest -q as the default command and make it show the full traceback on failure. For FastAPI, prefer tests built around TestClient because they exercise the actual routing, middleware, and exception handlers. Direct unit tests of service functions are useful, but they do not catch wrong status codes or missing response models.
Tell the agent to use app.dependency_overrides when a route depends on a database session or an external client. For example, override get_db with a fixture that yields a session around a test database. Do not accept a test that patches the function body but never sends an HTTP request; that gives false confidence.
After a green test run, ask the agent to run a linter such as python -m ruff check app tests. If you use type checking, run mypy app only if it is already part of the project. Review the diff for test-only changes that weaken assertions, such as changing assert response.status_code == 201 to assert response.status_code in (200, 201) just to make a failing test pass.
Running parallel agents on a FastAPI project with AgentVera
AgentVera runs real CLI tools such as Gemini CLI side by side in real terminal panels, which helps when a FastAPI project has several independent workstreams. Each agent can work in its own git worktree, so one can add an orders router while another fixes auth without overwriting files. When an agent’s turn ends, a second model reviews its code and links findings to file:line, which catches FastAPI-specific mistakes such as a missing response_model or an incorrect Depends signature. Checkpoints snapshot each turn, so a bad refactor of Pydantic schemas can be undone in one click. For more on coordinating agents, see AI agent orchestration for coding: 5 patterns and tools.
Final thoughts
Gemini CLI works well as a FastAPI pair programmer when you give it a clear GEMINI.md, request small changes, and enforce tests and linting before merge. The main risk is not the agent writing Python, but it silently changing conventions such as Pydantic v1 syntax, blocking the event loop, or miswiring dependency injection. Keep the review loop tight, and if you run several agents, isolate them in separate worktrees so FastAPI routers and schemas stay consistent.