# Gemini CLI: features, protocols, quickstart

## TL;DR

Gemini CLI is Google's Apache-2.0 terminal agent for Gemini models, with a free tier for personal Google accounts. It reads and edits code, runs shell commands, uses MCP servers, and delegates tasks to local subagents or remote A2A agents. It suits developers who want a terminal coding agent tied to Gemini models.

## Key facts

| Field | Value |
| --- | --- |
| Type | Harness |
| Languages / SDKs | TypeScript |
| License | Apache-2.0 |
| Pricing model | [Open core](https://geminicli.com/plans/) |
| Orchestration pattern | Supervisor |
| GitHub stars | 107,194 (as of 2026-09-30) |
| GitHub forks | 14,665 |
| Last push | 2026-09-30 |
| Latest release | v0.62.0 |
| Repository | [google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) |
| Website | [geminicli.com](https://geminicli.com) |
| Documentation | [geminicli.com](https://geminicli.com/docs/) |
| Last verified | 2026-09-30 |

## Key features

- Subagents run in their own context loop with their own prompt and tool list; the main agent calls each one as a tool, or the user forces one with @name. ([source](https://geminicli.com/docs/core/subagents))
- Built-in subagents include codebase_investigator, cli_help, generalist and an opt-in browser_agent; custom ones are Markdown files in .gemini/agents/. ([source](https://geminicli.com/docs/core/subagents))
- Remote subagents: a kind: remote agent file points at an A2A Agent Card, so the main agent can delegate to any compliant A2A agent. ([source](https://geminicli.com/docs/core/remote-agents))
- MCP servers (stdio or HTTP) are added in settings.json or with gemini mcp add, and subagents can be limited to specific MCP tools with wildcards. ([source](https://geminicli.com/docs/tools/mcp-server))
- Policy engine with TOML rules that allow, deny or ask before a tool call, scoped by tool, command prefix, MCP server or subagent. ([source](https://geminicli.com/docs/reference/policy-engine))
- Optional sandboxing (for example macOS Seatbelt or Docker) and checkpointing that snapshots files before AI edits so they can be restored. ([source](https://geminicli.com/docs/cli/sandbox))
- ACP mode (gemini --acp) lets editors and other developer tools drive the agent over JSON-RPC on stdio. ([source](https://geminicli.com/docs/cli/acp-mode))

## Architecture and orchestration pattern

Pattern: Supervisor.

Gemini CLI runs a single main agent loop in the terminal against Gemini models, with built-in tools for files, shell, web fetch and Google Search grounding, plus any MCP servers configured in `settings.json`. The same agent can be driven without the TUI through headless mode or, for editors, through ACP over stdio.

Delegation is supervisor-style. Each subagent is exposed to the main agent as a tool with the subagent's name; calling it runs the task in a separate context loop with the subagent's own system prompt, model and tool allowlist, and the subagent reports its findings back. Subagents cannot call other subagents, even when granted every tool. Remote subagents follow the same pattern but forward the task to an external agent over the A2A protocol, using an Agent Card URL or inline card JSON.

Context and memory are Markdown files: `GEMINI.md` files hold project instructions, and the agent writes durable facts to project, private or global memory files that load into later sessions. Checkpointing (off by default) snapshots project files before approved edits so they can be restored.

### Human in the loop

`--approval-mode` selects `default` (confirm tool calls), `auto_edit`, `yolo` or `plan` (read-only planning). The policy engine adds TOML rules that allow, deny or require confirmation for specific tools, shell command prefixes, MCP servers or individual subagents, and administrators can disable YOLO mode. The agent can pause with the `ask_user` tool to get a decision. With checkpointing enabled, each approved file-modifying tool call is preceded by a snapshot the user can restore. Unknown or unwanted subagents can be switched off with `/agents disable`.

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://geminicli.com/docs/tools/mcp-server) | Client: stdio and HTTP MCP servers configured in settings.json or with gemini mcp add; MCP tools can be scoped per subagent. |
| A2A | Yes (checked 2026-09-30) | [link](https://geminicli.com/docs/core/remote-agents) | Client: remote subagents (kind: remote) connect to any compliant A2A agent via its Agent Card, enabled by default (toggle lives under the experimental.enableAgents setting); the repo also publishes an @google/gemini-cli-a2a-server package. |
| AG-UI | Unknown (checked 2026-09-30) | — | No AG-UI or CopilotKit mention in the README or the full docs llms.txt; not in the AG-UI README integration list. |

## Best for

- Terminal coding and codebase questions on Gemini models, starting from the free personal tier. ([shortlist](https://multiagentguide.top/best/coding-agents.md))
- Delegating to remote agents built with ADK or other A2A frameworks from inside a coding session. ([shortlist](https://multiagentguide.top/best/research-agents.md))
- Organisations on Gemini Code Assist Standard or Enterprise that need admin controls such as disabling YOLO mode and MCP allowlists. ([shortlist](https://multiagentguide.top/best/enterprise-governance.md))

## Not for

- Using the Gemini CLI Google sign-in from other agents such as Claude Code, OpenClaw or OpenCode; the docs say this violates the terms.
- Workflows that need nested delegation, since subagents cannot call other subagents.
- Web front ends that expect an AG-UI event stream; no AG-UI support is documented.

## Quickstart

```sh
npm install -g @google/gemini-cli
```

Install verified 2026-09-30 (temp dir, Node v22.22.3, macOS arm64: local `npm i @google/gemini-cli` (no -g) ok, `npx --no-install gemini --version` ok, @google/gemini-cli 0.62.0. The official command uses `-g`; the same package was installed locally. Packages came from the registry.npmmirror.com mirror, so the version is the one that mirror served on this date. Install and import check only; not a functional test.).

```bash
npm install -g @google/gemini-cli
gemini                      # first run: sign in with Google

# a read-only auditor subagent for this project
mkdir -p .gemini/agents
cat > .gemini/agents/security-auditor.md <<'EOF'
---
name: security-auditor
description: Finds security problems in code and reports them without editing.
kind: local
tools:
  - read_file
  - grep_search
max_turns: 10
---
Review the code for injection, hard-coded secrets and unsafe file handling.
EOF

gemini mcp add github npx -y @modelcontextprotocol/server-github
gemini --approval-mode plan -p "@security-auditor review src/auth"
```

### Common pitfalls

- Requires Node.js 20+; the docs suggest 4 GB RAM for light use and 16 GB+ for long sessions on large codebases.
- `--yolo` is deprecated in favour of `--approval-mode=yolo`, and `--allowed-tools` was deprecated in favour of the policy engine.
- Sandboxing and checkpointing are both off by default; enable them before letting the agent run shell commands unattended.
- Signing in with Google gives Code Assist for individuals quotas (1,000 requests per user per day); a free Gemini API key has lower limits (250 per day).
- Do not reuse the CLI's Google OAuth login in third-party tools; use a Gemini API or Vertex AI key for other agents.

Official quickstart: https://geminicli.com/docs/get-started/installation

## Pros

- Apache-2.0 licensed with a free tier for personal Google accounts. ([source](https://github.com/google-gemini/gemini-cli))
- Built-in A2A client lets subagents live on other machines or frameworks. ([source](https://geminicli.com/docs/core/remote-agents))
- Per-subagent tool allowlists, including MCP wildcards, keep specialists isolated. ([source](https://geminicli.com/docs/core/subagents))
- Policy engine rules can target individual tools, command prefixes, MCP servers and subagents. ([source](https://geminicli.com/docs/reference/policy-engine))
- Checkpointing snapshots files before approved edits so changes can be rolled back. ([source](https://geminicli.com/docs/cli/checkpointing))

## Cons

- Subagents cannot call other subagents, so delegation is one level deep. ([source](https://geminicli.com/docs/core/subagents))
- Using the CLI's Google OAuth from third-party agents (the FAQ names Claude Code, OpenClaw and OpenCode) violates the terms and can lead to account suspension. ([source](https://geminicli.com/docs/resources/faq))
- The plans page says free-tier data may be used to improve products. ([source](https://geminicli.com/plans/))
- Sandboxing is disabled by default. ([source](https://geminicli.com/docs/reference/configuration))
- Daily request quotas apply on every tier, from 250 requests a day on a free API key to 2,000 on the top subscriptions. ([source](https://geminicli.com/docs/resources/quota-and-pricing))

## Alternatives

- [Claude Code](https://multiagentguide.top/tools/claude-code.md)
- [Codex CLI](https://multiagentguide.top/tools/codex.md)
- [OpenCode](https://multiagentguide.top/tools/opencode.md)
- [Cline](https://multiagentguide.top/tools/cline.md)
- [Aider](https://multiagentguide.top/tools/aider.md)

## FAQ

### Does Gemini CLI support MCP and A2A?

Yes. It is an MCP client for stdio and HTTP servers, and remote subagents connect to A2A agents through their Agent Cards. AG-UI support is not documented.

### Is Gemini CLI free?

The CLI is Apache-2.0. Signing in with a personal Google account gives a free quota of 1,000 requests a day; Google AI Pro, Ultra and Code Assist subscriptions or pay-as-you-go API keys raise the limits.

### Can Gemini CLI subagents call other subagents?

No. The docs describe recursion protection: a subagent cannot see or invoke other agents even with the * tool wildcard.

### Can I use my Gemini CLI login with OpenCode or OpenClaw?

No. The FAQ says reusing Gemini CLI's OAuth in third-party tools violates the terms; use a Google AI Studio or Vertex AI API key instead.

### What language is Gemini CLI written in?

TypeScript, distributed as the npm package @google/gemini-cli; it needs Node.js 20 or later.

## Sources

- [google-gemini/gemini-cli repository (README)](https://github.com/google-gemini/gemini-cli)
- [Gemini CLI homepage](https://geminicli.com)
- [Gemini CLI documentation](https://geminicli.com/docs/)
- [Installation](https://geminicli.com/docs/get-started/installation)
- [Subagents](https://geminicli.com/docs/core/subagents)
- [Remote subagents (A2A)](https://geminicli.com/docs/core/remote-agents)
- [MCP servers](https://geminicli.com/docs/tools/mcp-server)
- [Policy engine](https://geminicli.com/docs/reference/policy-engine)
- [Configuration reference](https://geminicli.com/docs/reference/configuration)
- [Sandboxing](https://geminicli.com/docs/cli/sandbox)
- [Checkpointing](https://geminicli.com/docs/cli/checkpointing)
- [ACP mode](https://geminicli.com/docs/cli/acp-mode)
- [Headless mode](https://geminicli.com/docs/cli/headless)
- [Memory files](https://geminicli.com/docs/tools/memory)
- [Quotas and pricing](https://geminicli.com/docs/resources/quota-and-pricing)
- [Plans](https://geminicli.com/plans/)
- [FAQ](https://geminicli.com/docs/resources/faq)
- [License, terms of service and privacy notices](https://geminicli.com/docs/resources/tos-privacy)
- [AG-UI README integration list](https://github.com/ag-ui-protocol/ag-ui)

## Unknown fields

protocols.agui: searched the README, the full docs text at https://geminicli.com/llms.txt (ag-ui, agui, copilotkit) and the AG-UI README integration list; nothing found.

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/gemini-cli