Gemini CLI Agentic Workflows: A 2026 Guide
The short version is this: you turn Gemini CLI into real automation by combining its ReAct loop with built-in tools, MCP servers, non-interactive scripting, GEMINI.md context, and the GitHub Action. Gemini CLI agentic workflows are what you get when you stop using the tool as a chat box and start handing it outcomes. It is an open-source AI agent from Google that lives in your terminal, reasoning about a goal, calling tools, and adjusting when something goes wrong, so it can carry out multi-step work rather than answer a single prompt. The first commands are easy to run, but the pieces that make automation trustworthy, connecting MCP servers, scripting it non-interactively, teaching it your conventions, and wiring it into GitHub, are not obvious from the welcome screen. This guide walks that path end to end.
'/%3E%3Cpath%20d='M350%20100%20H398'%20marker-end='url(%23a)'/%3E%3Cpath%20d='M530%20100%20H578'%20marker-end='url(%23a)'/%3E%3Cpath%20d='M465%20130%20V165%20H105%20V132'%20marker-end='url(%23a)'/%3E%3C/g%3E%3Cdefs%3E%3Cmarker%20id='a'%20markerWidth='8'%20markerHeight='8'%20refX='6'%20refY='3'%20orient='auto'%3E%3Cpath%20d='M0%200L6%203L0%206z'%20fill='%231A73E8'/%3E%3C/marker%3E%3C/defs%3E%3Ctext%20x='285'%20y='185'%20fill='%236B7280'%20font-size='12'%3EThe%20loop%20repeats%20until%20the%20goal%20is%20met%20or%20recovery%20fails%3C/text%3E%3C/g%3E%3C/svg%3E)
Before anything else: Gemini CLI is open source under the Apache 2.0 license and free to start. Signing in with a personal Google account gives a generous free tier. We cover the exact allowances, and how they change with an API key or Vertex AI, in the first step.
Set Up Gemini CLI for Agentic Workflows
Getting started takes one prerequisite and one decision. The prerequisite is Node.js 20 or newer; the CLI runs on macOS, Linux, and Windows, and it is preinstalled in Google Cloud Shell if you would rather not set up anything locally. From there you can run it on demand with npx, or install it globally with npm, Homebrew, MacPorts, or Anaconda so the gemini command is always available.
Choosing how to authenticate
The sign-in method you pick sets both your limits and who is billed. A personal Google account gives the simplest free tier with no API key to manage. An API key or Vertex AI is what you graduate to as usage grows.
| Method | What You Get |
|---|---|
| Personal Google account | Free tier: 60 requests per minute and 1,000 per day with Gemini 3 models and a 1M-token context, no API key to manage |
| Gemini API key | Free tier of 1,000 requests per day with Gemini 3, plus optional usage-based billing as you scale |
| Vertex AI | Higher rate limits for teams and production, billed through a Google Cloud account |
| Gemini Code Assist | Individual, Standard, or Enterprise quotas, shared between the CLI and Code Assist agent mode in VS Code |
On the free-tier numbers: the 60 per minute and 1,000 per day figures are vendor-reported as of June 2026 and framed as a preview allowance, so they may change. An older docs page cited a smaller API-key allowance with an earlier model, which is why model version matters. Confirm current limits in the official documentation before you build around a hard number.
The ReAct Loop: How Gemini CLI Agentic Workflows Think
The core of Gemini CLI is a ReAct agent, short for reason and act. Rather than producing one answer to one prompt, it works in a loop: it reasons about the goal, builds a multi-step plan, calls a tool to take an action, observes the result, and then decides what to do next. When a step fails, it reads the error and attempts to recover instead of stopping. That loop is the difference between a chatbot and an agent, and it is what lets the CLI complete tasks that take several moves.
In practice this means you can hand it an outcome rather than a sequence of instructions. Ask it to find why a test is failing, and it will read the relevant files, run the test to see the actual error, form a hypothesis, make an edit, and run the test again to check the fix. Each action feeds the next decision, so the agent narrows in on the goal across several turns.
The mental model that pays off is to think in goals and guardrails, not keystrokes. You describe what done looks like and which tools the agent may use; it works out the steps. Your job shifts from typing each edit to reviewing the plan and the results, which is exactly where automation becomes worthwhile.
Built-In Tools: The Agent's Hands
A reasoning loop is only useful if the agent can act on the world, and that is what the built-in tools provide. Out of the box, with no extra setup, Gemini CLI can do file operations, run shell commands, fetch web pages, and ground its answers in Google Search. These are the actions the ReAct loop calls between its reasoning steps.
- File operations let the agent read, write, and edit files in your project, which is how it makes the changes a task requires.
- Shell commands let it run build steps, tests, linters, and other tools you already use from the terminal, then read their output to decide what is next.
- Web fetch pulls in the contents of a URL, so the agent can work from a page of documentation or an issue you point it at.
- Google Search grounding lets it look up current information and anchor its answers to real results rather than relying only on what the model already knows.
Together these cover most day-to-day automation: read the code, run a command, check the result, fix what is wrong. When you need to reach beyond the terminal, to a database, a ticketing system, or a media-generation model, that is where MCP servers come in, which is the next step.
Worth knowing: shell access carries real risk, so review what the agent proposes to run before approving it. The same capability that lets it run your test suite also lets it run any command, which is why the review step in the loop matters.
Connect MCP Servers
To extend the agent past its built-in tools, Gemini CLI supports the Model Context Protocol, an open standard for giving an AI tool access to external systems and data sources. You register MCP servers in the CLI's configuration file at ~/.gemini/settings.json. Once a server is registered, its tools become available to the agent, and the ReAct loop can call them the same way it calls a built-in tool.
This is the seam where Gemini CLI plugs into the rest of your stack. An MCP server can expose a database, a project tracker, a cloud API, or an internal service, so the agent can read from and act on systems that live well outside the terminal. Gemini CLI MCP support is what lets the same loop reach those systems, and it is where most serious Gemini CLI agentic workflows start to pay off.
Media generation through MCP
One use worth highlighting is media generation. Through MCP, the agent can reach Google's generative-media models: Imagen for images, Veo for video, and Lyria for music. That turns a text instruction in your terminal into a request for generated media as part of a larger workflow, rather than a separate task in a separate tool.
The pattern is the same regardless of what the server connects to: register it once in settings, and its capabilities join the agent's toolset. Add servers as concrete needs arise rather than wiring everything up before you have a reason to, and confirm each server's exact configuration against its own documentation.
Automate in Scripts: Non-Interactive Mode
Interactive use is where you learn the tool, but automation lives in scripts, and Gemini CLI is built for that too. In non-interactive mode you pass a single prompt and read the result back, with no chat session to sit in front of. That lets you call the agent from a shell script, a cron job, or a pipeline step.
The piece that makes scripting reliable is structured output. With --output-format json the CLI returns a single JSON object your script can parse, and --output-format stream-json emits events as they happen for longer-running work. Either way, another program can consume the agent's output instead of a human reading prose.
The practical pattern is to prototype the prompt interactively until the agent does what you want, then move that prompt into a script with a structured output flag. From there you can schedule it, chain it with other commands, or drop it into continuous integration, which is exactly what the GitHub Action does for you. Scripted, structured runs like these are the backbone of most production Gemini CLI agentic workflows.
GEMINI.md and Custom Commands
Left to itself, the agent reasons from the project it can see. You make it sharper by teaching it your conventions, and the way you do that is a GEMINI.md file. It is a custom context file you place in your project: instructions, conventions, and background the agent reads so you do not have to restate them in every prompt. Tell it once how your code is structured, what to avoid, and how you like changes made, and that guidance carries across the session.
Alongside context, Gemini CLI lets you define custom commands for tasks you repeat. Instead of retyping the same multi-line instruction, you capture it once and invoke it by name, so a routine job like preparing a release note or running a standard review becomes a single command.
How they work together
GEMINI.md sets the standing context, the things that are true of every task in this project, while custom commands capture the specific jobs you run often. Used together they make the agent behave consistently: the context keeps its output aligned with your project, and the commands keep your common workflows fast and repeatable.
Start small: a short GEMINI.md that captures three or four real conventions you would otherwise repeat is worth more than an exhaustive one written up front. Add to it as you notice the agent missing something you care about.
GitHub Action Workflows
The scripting foundation pays off in continuous integration through the official Gemini CLI GitHub Action. It brings the agent into your repository's workflows so it can act on pull requests and issues automatically. Two uses are built around it: pull-request review, where the agent inspects a change and leaves feedback, and issue triage, where it reads incoming issues and helps sort them.
You can also invoke the agent on demand from inside a pull request or issue by mentioning @gemini-cli, the same way you would ask a teammate to take a look. That makes the agent a participant in the review conversation rather than a separate tool you switch to.
Conversation checkpointing
For longer sessions, Gemini CLI supports conversation checkpointing: it can save the state of a session so you can resume it later instead of starting over. On work that spans more than one sitting, or that you want to pick back up after a break, checkpointing keeps the accumulated context so the agent does not lose its place.
The throughline: the same agent runs interactively in your terminal, non-interactively in a script, and inside GitHub through the Action. Learn the loop once and the same workflow scales from your laptop to your pipeline. New to the tool itself? Start with our guide to using Gemini CLI, then come back here to build out your Gemini CLI agentic workflows.
Common Agentic Pitfalls
These are the snags people hit when they move from running a prompt to building real Gemini CLI agentic workflows, with the practical answer for each.