Gemini CLI with NestJS: A Practical Agent Workflow

Gemini CLI is a terminal coding agent from Google that you start by running gemini in your project folder. On a NestJS project it works best when you give it a concise GEMINI.md with your build/test/lint commands, NestJS conventions, and clear boundaries. The result is less guessing and more reliable diffs for modules, DTOs, and tests. For the basics of the tool, see Gemini CLI.

Why Gemini CLI fits NestJS work

Gemini CLI suits NestJS work because NestJS is highly structured, and an agent can follow that structure if you document it. Controllers, providers, and modules have predictable decorators and import patterns; DTOs use class-validator; tests use Jest with Nest’s testing utilities. Gemini CLI can generate idiomatic Nest code quickly, keep @Injectable(), @Controller(), and @Module() wiring consistent, and write focused Jest specs. The same structure that helps humans also gives the agent a small search space, which reduces hallucinated imports and wrong file placement.

Set up GEMINI.md for a NestJS project

Set up GEMINI.md at the repository root. The agent reads this file automatically at the start of a session. Keep it short and specific; longer does not equal better. Include commands exactly as you run them, folder conventions, and Nest-specific rules. Do not put secrets; this file is committed.

Here is a realistic GEMINI.md for a NestJS project using Prisma:

# GEMINI.md

## Commands
- Install: `npm ci`
- Build: `npm run build`
- Test: `npm test -- --runInBand`
- Lint: `npm run lint`
- Format: `npm run format`

## Project conventions
- Each feature gets its own module under `src/<feature>/`.
- Controllers handle HTTP and delegate to providers; no business logic in controllers.
- All request bodies and query params use DTO classes with class-validator.
- Use `@IsOptional()` for optional fields and `@Type(() => Number)` for numeric query params.
- Providers are declared in the module where they are used; export them only when another module needs them.
- Database access lives in services or repositories; use the shared `PrismaService` from `src/prisma/`.
- Write Jest tests next to production files as `*.spec.ts`.
- Never run `nest generate` from the agent; edit files directly.
- If unsure where a file belongs, mirror the structure of `src/users/`.

If you use TypeORM instead of Prisma, replace the database rule with repository classes and @InjectRepository() conventions.

A working loop with example prompts

A working loop with Gemini CLI is plan, small step, verify, review. Start the agent in the project root with gemini, then state the outcome and constraints. Ask it to plan first for larger changes; for small ones, ask for a diff. After each change, run the test/lint/build commands from GEMINI.md, then inspect git diff yourself. Do not let the agent run multiple unverified steps in a row.

Example prompts for typical NestJS work:

• Create a users module with UsersController, UsersService, CreateUserDto, and UpdateUserDto. Add class-validator rules, export the service, and register the module in AppModule.
• Add GET /users/:id that returns a user by id. Use ParseUUIDPipe, map the entity to a UserResponseDto, and add a Jest unit test for the controller with a mocked service.
• Refactor AuthService to inject JwtService through the constructor and add unit tests that mock JwtService. Keep the existing method signatures.
• Add a posts table to the Prisma schema with a many-to-one relation to users, generate the Prisma client, and implement create and list methods in PostsService.
• Fix the failing test in src/users/users.service.spec.ts without changing production code unless necessary. Explain the root cause before editing.

This loop feels like pair programming; for a deeper workflow, see AI pair programming: how to work with a coding agent.

Typical NestJS tasks and where to watch closely

Gemini CLI handles NestJS boilerplate well: generating modules, controllers, providers, DTOs with validation decorators, guards, interceptors, and pipes. It is also good at writing unit tests with Nest’s testing utilities, mocking TypeORM repositories or Prisma clients, and updating Prisma schemas. It can follow module boundaries if GEMINI.md spells them out.

Watch the agent closely in these NestJS-specific areas:

• Dependency injection: it may forget @Injectable() on a provider or export a provider from the wrong module. Check constructor injection parameters match provider tokens.
• class-validator: the agent may add decorators but forget to enable ValidationPipe in main.ts, or may use @IsInt() on a query param without @Type(() => Number), so validation fails.
• Module imports: it may import a service directly across module boundaries instead of importing the module; this breaks Nest’s dependency graph.
• Jest module resolution: NestJS projects often use path aliases; if tests fail with “Cannot find module”, compare tsconfig.json and jest config. The agent may modify one without the other.
• TypeORM/Prisma: with TypeORM, entity decorators can create circular imports; with Prisma, tests may fail if the client is not mocked or the database is not cleaned. Ask the agent to use an in-memory mock, not a real database, for unit tests.
• Lifecycle hooks: if it adds OnModuleInit or OnModuleDestroy, check for proper implements and that async operations are awaited.

Testing and verification with the agent

Testing is the main control point when working with Gemini CLI on NestJS. Always run the commands from GEMINI.md after each agent turn. NestJS projects use Jest by default, often with separate unit and end-to-end tests. Use npm test -- --runInBand for unit tests to avoid worker conflicts with database mocks. For e2e tests, use npm run test:e2e if defined; do not let the agent change the e2e setup unless you ask.

Use this table as a quick verification pass:

After tests pass, review the diff for the pitfalls above: missing @Injectable(), missing @Type on numeric query DTOs, or changed module imports. If a test fails, ask the agent to explain the root cause first, then make a minimal fix.

Running several Gemini CLI agents on one NestJS project

Running several Gemini CLI agents on one NestJS project is easier with AgentVera, a desktop app that puts each agent in its own terminal panel. For NestJS work, the most valuable features are separate git worktrees, automatic code review, checkpoints, and an approval queue. Worktrees keep module edits isolated; code review catches missing decorators or broken DI; checkpoints let you undo a bad scaffold. For patterns, see /en/blog/ai-agent-orchestration/.

Wrap-up

Gemini CLI becomes much more predictable on a NestJS project once GEMINI.md documents commands and Nest-specific rules. Keep the loop tight: ask for small diffs, run tests and lint, review DI and validation changes, and use checkpoints when needed. With those habits, the agent handles boilerplate and tests well, and you stay in control of the architecture.