# Gemini CLI in Laravel: a practical developer guide

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

Learn how to use Gemini CLI in a Laravel project: set up GEMINI.md, run small validated changes, review Eloquent and migration edits, and test after each turn.

**In short:**

- A project-specific GEMINI.md with exact commands and Laravel rules keeps Gemini CLI aligned with your codebase.
- Work in small layers: let the agent change one piece, run PHPUnit or Pest, then review the diff before continuing.
- Gemini CLI handles models, migrations, form requests and tests well, but check eager loading, mass assignment and queue serialization.

[Gemini CLI](/en/agents/gemini-cli/) is a terminal coding agent that reads your Laravel project and its GEMINI.md instructions. This guide shows how to use `gemini` in a Laravel project for practical daily work: setting up the agent, prompting in small validated steps, reviewing risky Eloquent and migration edits, and using tests to keep the suite green.

## Why Gemini CLI fits Laravel development

Laravel’s structure is conventional enough that a coding agent can be productive quickly once it understands `app/Models`, `app/Http`, `database/migrations`, `routes` and `tests`. Gemini CLI can follow Eloquent relationships, read migration history, generate form requests, update factories, and write Artisan commands without inventing new abstractions. It can also inspect existing Blade components, queue jobs, and service classes to match your namespace and naming style. The main value is not code generation in a vacuum; it is code generation inside your existing conventions, so it can add a model, migration, policy and feature test that look like the rest of the application.

## Set up GEMINI.md with the right Laravel commands and rules

Start by running `gemini` in the Laravel project root. Before relying on it, create a `GEMINI.md` file at the project root with the commands the agent should run and the rules it must follow. Keep it short; the best file is about a screen long.

```markdown
# Laravel project notes for Gemini CLI

## Commands
- Install: `composer install`
- Build assets: `npm run build`
- Run tests: `php artisan test` (or `./vendor/bin/pest`)
- Lint: `./vendor/bin/pint --test`
- Static analysis: `./vendor/bin/phpstan analyse --memory-limit=1G`

## Conventions
- Models live in `app/Models`, plural table names, `$fillable` or `$guarded` is explicit.
- Controllers are thin: authorize in form requests or policies, keep business logic in actions or services.
- Migrations are append-only on shared branches; use fresh migrations locally if needed.
- Blade views: use components for repeating UI, keep PHP out of templates except simple loops/conditionals.
- Queue jobs: one job class per public method in `app/Jobs`, always type hint dependencies in `handle`.

## Rules
- Do not edit `composer.lock` or `package-lock.json` unless asked.
- Do not run destructive commands like `migrate:fresh` on the main database without confirmation.
- Prefer dependency injection over facades in new code, but existing facades are fine.
- Use Pest for new tests; keep PHPUnit compatibility if the suite is PHPUnit-based.
```

Update the commands to match your real stack. If you use PHPStan or Larastan, include the exact command; if not, remove it. The rules matter more than the commands because they prevent common Laravel-specific mistakes, such as running `migrate:fresh` on a shared database, editing lock files, or bypassing policies. Also tell the agent where your tests live and whether you use Pest or PHPUnit, because feature tests are the fastest safety net. If you are new to the agent, see [How to use Gemini CLI: a step-by-step guide](/en/blog/how-to-use-gemini-cli/).

## Use a small plan, edit, test, review loop

Use a tight loop: plan the change in one or two sentences, let the agent make a small edit, run the relevant test command, review `git diff`, then continue only if the suite is green. For Laravel, the loop should usually touch one layer at a time: migration, then model/factory, then controller/form request, then tests. That makes it easier to spot what broke, especially when a single model change affects ten other files. Ask for a list of files the agent plans to touch before it edits anything. Then review the exact diff line by line. Treat the agent as a fast pair programmer that still needs your review, as described in [AI pair programming: how to work with a coding agent](/en/blog/ai-pair-programming/).

Example prompts for typical Laravel tasks:

- Add a paginated `posts` index endpoint with authorization through `PostPolicy`, a form request for query filters, and a Pest feature test.
- Add a nullable `published_at` timestamp to the `posts` table, update the model, factory and API resource, and run the focused `PostTest`.
- Refactor `app/Services/CheckoutService.php` into readable private methods without changing public behavior, then run the checkout-related tests.
- Create a queued `SendWelcomeEmail` job dispatched after user registration, with a failed-job test and a feature test for the dispatch.
- Find every controller action that reads `status` directly from the request and add a form request validation rule without breaking existing tests.

For each prompt, ask the agent to show the diff before running the full suite. Start with the test command for only the affected file; if that passes, run the full suite.

## Where Gemini CLI shines and where it needs extra review in Laravel

Gemini CLI is strongest when you stay within Laravel’s conventional boundaries. It handles adding or altering migrations, models, factories and seeders well, especially when the instructions mention `app/Models` naming and `$fillable` rules. It writes form requests, controllers, resource classes, queued jobs, listeners and Pest/PHPUnit tests that follow existing patterns. It can also generate Artisan commands and update Blade components when the component folder is specified.

Watch it closely in these areas:

- Eager loading: the agent may add a relationship call without `with()` and introduce N+1 queries in loops.
- Mass assignment: new columns may be omitted from `$fillable` or `$guarded`; always check the model diff.
- Migrations: the agent sometimes edits an existing migration instead of adding a new one on shared branches; reject changes to old migration files unless you explicitly requested a fresh migration.
- Queue jobs: check that the job’s constructor and `handle` only pass scalar IDs or small DTOs, not models with closure dependencies; missing `ShouldQueue` can turn jobs synchronous by accident.
- Authorization: the agent may add a controller method but forget the policy or form request authorization; verify `authorize` returns true or that middleware applies.
- Service providers and middleware: changes to `AppServiceProvider` or kernel files can affect route loading and rate limiting; review boot order carefully.

## Verify agent changes with tests, formatting, and static analysis

Make the agent run tests, but always run them yourself before accepting. Use focused tests during iteration and the full suite before merging. A Laravel project usually has three layers that need verification: the test suite, code style, and static analysis if configured.

| Command | Purpose |
|---------|---------|
| `php artisan test --filter=PostTest` | Run one test class or method while iterating on a single feature. |
| `php artisan test` | Run the full PHPUnit or Pest suite before finishing a change. |
| `./vendor/bin/pint --test` | Check Laravel code style; use `./vendor/bin/pint` to fix violations. |
| `./vendor/bin/phpstan analyse` | Catch type and relationship mistakes if Larastan/PHPStan is installed. |

Review the diff for missing eager loading, accidental mass assignment changes, and database migrations that rename columns without backfilling data. When the agent edits queue jobs, run the specific job test and, if possible, run `php artisan queue:work --once` locally with a test transport to catch serialization problems. Use `php artisan route:list` and `php artisan migrate:status` after route or migration changes to confirm the application still boots.

## Run several Gemini CLI agents on one Laravel project with AgentVera

For larger Laravel changes, run several Gemini CLI agents in AgentVera. Parallel agents can each work in their own git worktree, so concurrent edits to migrations, models and tests never overwrite each other. After each agent turn, an automatic code review points to file:line issues such as a missing `$fillable` guard or a broken Eloquent relationship. Checkpoints store every turn, so a bad migration or service refactor can be undone in one click and replayed step by step. This is one of the patterns in [AI agent orchestration for coding: 5 patterns and tools](/en/blog/ai-coding-agent-orchestration/).

## Wrap-up

Gemini CLI becomes a practical Laravel tool when you give it a small, explicit GEMINI.md and keep changes to one layer per turn. Run the test suite often, read the diff for Eloquent and migration hazards, and treat the agent as a fast pair programmer that still needs your review.

## Frequently asked questions

**How do I start Gemini CLI in a Laravel project?** Run gemini from the project root. Create a GEMINI.md file there with Laravel-specific commands, conventions and rules; Gemini CLI reads that file before working on the project.

**What should I put in GEMINI.md for Laravel?** Include the exact commands for installing dependencies, building assets, running tests, linting and static analysis. Add folder conventions for models, controllers, migrations and tests, plus rules like never run migrate:fresh on a shared database and never edit lock files.

**Can Gemini CLI write Laravel migrations and Eloquent models?** Yes, it can generate migrations, models, factories and relationships. Review column types, indexes, foreign keys, timestamps, $fillable/$guarded and relationship naming because those are the most likely spots for subtle mistakes.

**How do I keep Gemini CLI from breaking my Laravel tests?** Ask for one small change per turn, run the relevant test command after each turn, and review git diff before accepting. Use GEMINI.md rules to avoid destructive migrations and unauthorized behavior changes.

---

**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/