Gemini CLI
Task-indexed reference for Google Gemini CLI 0.36.0. Verified locally on 2026-04-08 from gemini --help and the built-in skill-creator plugin source.
This SKILL.md is the navigation index. Detailed documentation lives in references/. Read only what the current task needs.
When to use
- Building anything that calls
gemini from the shell or a script (headless -p mode)
- Authoring or porting Gemini skills, extensions, MCP servers, hooks
- Editing
~/.gemini/settings.json, ~/.gemini/GEMINI.md, project GEMINI.md
- Migrating Claude Code hooks via
gemini hooks migrate
- Cross-referencing Gemini against Claude Code, Codex CLI, or GitHub Copilot CLI
- Writing the Policy Engine policy files that replaced
--allowed-tools
Versions covered
| Component |
Version (verified locally 2026-04-08) |
| Gemini CLI |
0.36.0 |
@google/gemini-cli-a2a-server (A2A GA) |
0.36.0 (npm, published 2026-04-07) |
| Built-in skill-creator |
bundled with 0.36.0 |
Quick task index
Headless / scripted invocation
| Task |
Read |
| Run a one-shot prompt and exit |
references/headless.md |
| Approval modes (default / auto_edit / yolo / plan) |
references/headless.md (Approval Modes section) |
| Output formats (text / json / stream-json) |
references/headless.md (Output formats section) |
| Sandbox mode |
references/headless.md (Sandbox section) |
Hybrid mode (-i, --prompt-interactive) |
references/headless.md (Hybrid section) |
| Resume / list / delete sessions |
references/headless.md (Sessions section) |
Skills and extensions
| Task |
Read |
| Author a Gemini skill (frontmatter rules) |
references/skills-and-extensions.md (Skill Format section — verified from built-in skill-creator) |
| Install a skill from git or local path |
gemini skills install <git-url-or-path> (see skills-and-extensions.md) |
| Symlink a skill for in-place dev |
gemini skills link <path> |
| List, enable, disable, uninstall skills |
gemini skills {list,enable,disable,uninstall} |
| Author / use extensions |
references/skills-and-extensions.md (Extensions section) |
| Generate extension boilerplate |
gemini extensions new <path> [template] |
| Validate an extension manifest |
gemini extensions validate <path> |
Policy engine and tool control
| Task |
Read |
Replace deprecated --allowed-tools |
references/policy-engine.md |
| Write a read-only CI policy |
references/policy-engine.md (Read-only CI policy section) |
Difference between --policy and --admin-policy |
references/policy-engine.md (Scope semantics section) |
Memory, context, files
| Task |
Read |
GEMINI.md hierarchy and @file.md imports |
references/gemini-md.md |
| Add extra include directories |
--include-directories flag |
| Settings.json schema |
references/settings-schema.md |
Hooks (migrated from Claude Code)
| Task |
Read |
| Migrate Claude Code hooks to Gemini |
references/hooks.md (gemini hooks migrate) |
| Limitations and live-compat semantics |
references/hooks.md (Limitations section) |
MCP servers
| Task |
Read |
| Add a stdio or http MCP server |
gemini mcp add <name> <commandOrUrl> [args...] (see references/mcp.md) |
| List, enable, disable, remove MCP servers |
gemini mcp {list,enable,disable,remove} |
| Restrict to specific MCP servers per invocation |
--allowed-mcp-server-names |
Use in ~/.gemini/settings.json |
references/settings-schema.md |
| Already-installed example |
references/mcp.md (nanobanana extension example) |
A2A and ACP
| Task |
Read |
| Run Gemini CLI as an A2A server |
references/a2a-and-acp.md (A2A section — @google/gemini-cli-a2a-server@0.36.0 verified GA) |
| Run Gemini CLI as an ACP server (e.g. for Zed editor) |
references/a2a-and-acp.md (ACP section — --acp flag) |
| Difference between A2A, ACP, and MCP |
references/a2a-and-acp.md (Three protocols section) |
Authentication
| Task |
Read |
| OAuth personal account (default) |
references/auth.md (OAuth section — gemini auth login) |
| Direct API key |
references/auth.md (GEMINI_API_KEY) |
| Vertex AI via ADC |
references/auth.md (Vertex section — GOOGLE_GENAI_USE_VERTEXAI=1, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, gcloud auth application-default login) |
| Service account JSON |
references/auth.md (GOOGLE_APPLICATION_CREDENTIALS=<path.json>) |
| Auth decision table |
references/auth.md (Decision table section) |
Verification
Run scripts/verify-gemini-install.sh after a gemini upgrade. The script:
- Captures
gemini --version, gemini --help, gemini skills --help, gemini extensions --help, gemini hooks --help, gemini mcp --help
- Lists
gemini skills list --all and gemini extensions list
- Verifies
gemini hooks migrate subcommand still exists
- Checks
~/.gemini/settings.json parses as JSON if present
- Reports auth state hint
Top-level subcommands (verified)
mcp Manage MCP servers (add | remove | list | enable | disable)
extensions Manage extensions (install | uninstall | list | update | enable | disable | link | new | validate | config)
skills Manage agent skills (list | enable | disable | install | link | uninstall)
hooks Manage hooks — only one subcommand: migrate (one-shot import from Claude Code)
[query..] Default — launches interactive mode unless -p/--prompt is set
gemini extensions and gemini extension are aliases. Same for gemini skills / gemini skill. Same for gemini hooks / gemini hook.
Host directive (verified 2026-05-04)
Canonical pattern for any headless gemini call on this host:
GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -p "<prompt>"
- Empty env prefix forces OAuth subscription routing (otherwise
GOOGLE_CLOUD_PROJECT=thecpuwebwoov01 inherits in and 403s).
-m gemini-3.1-pro-preview requests top-tier — silently downgrades to lower tier on capacity exhaustion or routing decisions, but pin it anyway to express intent.- Model self-identification is unreliable (a model asked "what model are you?" may return the CLI name, the wrong model id, or a sibling). When the served model matters, append a
served_by=<model_id> probe line to the prompt and capture it in the output.
- Verdict / output quality varies by served tier (verified: same ballot prompt returned different verdicts on
gemini-2.5-pro vs gemini-3.1-pro-preview). Record served_by in any deliberation artifact.
Headless (-p) cheat sheet
# Canonical (always do this on this host)
GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -p "summarize this file" < notes.md
# JSON output
GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -p --output-format json "list TODOs in this repo"
# Hybrid: run a prompt then drop into interactive
GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -i "investigate this bug" --include-directories ./src
# Auto-approve all (YOLO) — sandbox + non-interactive
GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -p -y -s "refactor this function"
# Read-only plan mode
GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -p --approval-mode plan "what would you change in this file?"
# Restrict via Policy Engine
GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -p --policy ./ci-readonly.policy "review this PR"
# Pin specific extensions
GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -p -e my-skill -e nanobanana "build a thumbnail for this post"
# Resume the most recent session
GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -r latest "continue where we left off"
See references/headless.md for the full surface and references/policy-engine.md for policy file format.
Approval modes (verified)
| Mode |
Behaviour |
default |
Prompt for approval on each tool use |
auto_edit |
Auto-approve edit tools, prompt for everything else |
yolo |
Auto-approve all tools (also via -y) |
plan |
Read-only mode |
Anti-patterns
| Don't |
Why |
Add fields to skill frontmatter beyond name and description |
Gemini silently rejects extras. Verified from built-in skill-creator/SKILL.md: "Do not include any other fields in YAML frontmatter." |
Use --allowed-tools |
DEPRECATED. Use the Policy Engine (--policy, --admin-policy). The flag still works but throws a deprecation warning. |
Expect gemini skills install to update the symlink that bob created |
install will likely replace symlinks with real directories. Use gemini skills link <path> for in-place dev. Canonical source stays in ~/.claude/skills/. |
| Treat A2A and ACP as the same thing |
A2A is agent-to-agent (@google/gemini-cli-a2a-server). ACP is the Agent Client Protocol — Gemini CLI acts as an ACP server for clients like Zed. Different protocols. |
Expect gemini hooks migrate to keep migrated hooks in sync |
One-shot import. Treat the output as a generated artifact. Re-run after editing source hooks. |
Skip the JSON parse check on ~/.gemini/settings.json |
Malformed JSON silently breaks Gemini config loading. Run the verify script. |
Put all skills under ~/.gemini/skills/ and forget about Claude |
Canonical location is ~/.claude/skills/<name>/. Symlink to ~/.gemini/skills/<name>/ and run gemini skills link <path>. See cross-tool-portability/install-matrix.md. |
Use --raw-output without --accept-raw-output-risk |
Disables sanitization of model output, allows ANSI escapes. Security risk if model output is untrusted. |
| Trust model self-ID for "which model answered me?" |
Verified 2026-05-04: model self-ID is unreliable on this CLI — same prompt asking "what model are you?" returned gemini-cli (the CLI name) on one run and gemini-2.5-pro on another, when the actual served model was different. Capture served_by at the call layer with a structured probe line, not from the model's free-text answer. |
Assume -m <model> deterministically picks that model |
Verified 2026-05-04: requesting -m gemini-2.5-pro was actually served by gemini-3.1-pro-preview after settings.json updates. The -m flag is advisory; settings.json + server-side routing dominates. Always capture served_by; never assume what was asked == what was served. |
Drop the GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= env prefix on this host |
Shell sets GOOGLE_CLOUD_PROJECT=thecpuwebwoov01 for vertex-banana / GA tooling. Without the empty overrides, gemini -p fails 403 from cloudcode-pa.googleapis.com even with valid OAuth creds. |
See also
references/skills-and-extensions.md — verified Gemini skill format from local built-inreferences/hooks.md — gemini hooks migrate semanticsreferences/policy-engine.md — what replaced --allowed-toolsreferences/a2a-and-acp.md — A2A GA confirmation, ACP --acp flagreferences/auth.md — 4 auth flows, decision tablereferences/settings-schema.md — ~/.gemini/settings.json structure (Gemini-research only — unverified)references/gemini-md.md — GEMINI.md hierarchy, importsreferences/mcp.md — gemini mcp subcommands, nanobanana exampleclaude-code-cli — Claude Code CLI counterpartgh-copilot-cli — GitHub Copilot CLI counterpartgcp-workstations — Vertex auth on a GCP Workstationresearch-for-skills/cross-tool-portability/ — rules for skills that span multiple CLIscodex-orchestration — Gemini MCP integration patterns
Source: joogy06/agent-foundry — distributed by TomeVault.
1---2name: gemini-cli-43description: Use when working with Google Gemini CLI (`gemini`) — headless and interactive modes, the policy engine, skills, extensions, hooks migration, MCP servers, A2A and ACP protocols, GEMINI.md hierarchy, and authentication. Covers Gemini CLI 0.36.0 (April 2026). Includes verified ground truth from the local install.4---56# Gemini CLI78Task-indexed reference for Google Gemini CLI 0.36.0. Verified locally on 2026-04-08 from `gemini --help` and the built-in `skill-creator` plugin source.910This SKILL.md is the navigation index. Detailed documentation lives in `references/`. Read only what the current task needs.1112## When to use1314- Building anything that calls `gemini` from the shell or a script (headless `-p` mode)15- Authoring or porting Gemini skills, extensions, MCP servers, hooks16- Editing `~/.gemini/settings.json`, `~/.gemini/GEMINI.md`, project `GEMINI.md`17- Migrating Claude Code hooks via `gemini hooks migrate`18- Cross-referencing Gemini against Claude Code, Codex CLI, or GitHub Copilot CLI19- Writing the Policy Engine policy files that replaced `--allowed-tools`2021## Versions covered2223| Component | Version (verified locally 2026-04-08) |24|---|---|25| Gemini CLI | 0.36.0 |26| `@google/gemini-cli-a2a-server` (A2A GA) | 0.36.0 (npm, published 2026-04-07) |27| Built-in skill-creator | bundled with 0.36.0 |2829## Quick task index3031### Headless / scripted invocation3233| Task | Read |34|---|---|35| Run a one-shot prompt and exit | `references/headless.md` |36| Approval modes (default / auto_edit / yolo / plan) | `references/headless.md` (Approval Modes section) |37| Output formats (text / json / stream-json) | `references/headless.md` (Output formats section) |38| Sandbox mode | `references/headless.md` (Sandbox section) |39| Hybrid mode (`-i, --prompt-interactive`) | `references/headless.md` (Hybrid section) |40| Resume / list / delete sessions | `references/headless.md` (Sessions section) |4142### Skills and extensions4344| Task | Read |45|---|---|46| Author a Gemini skill (frontmatter rules) | `references/skills-and-extensions.md` (Skill Format section — verified from built-in skill-creator) |47| Install a skill from git or local path | `gemini skills install <git-url-or-path>` (see `skills-and-extensions.md`) |48| Symlink a skill for in-place dev | `gemini skills link <path>` |49| List, enable, disable, uninstall skills | `gemini skills {list,enable,disable,uninstall}` |50| Author / use extensions | `references/skills-and-extensions.md` (Extensions section) |51| Generate extension boilerplate | `gemini extensions new <path> [template]` |52| Validate an extension manifest | `gemini extensions validate <path>` |5354### Policy engine and tool control5556| Task | Read |57|---|---|58| Replace deprecated `--allowed-tools` | `references/policy-engine.md` |59| Write a read-only CI policy | `references/policy-engine.md` (Read-only CI policy section) |60| Difference between `--policy` and `--admin-policy` | `references/policy-engine.md` (Scope semantics section) |6162### Memory, context, files6364| Task | Read |65|---|---|66| `GEMINI.md` hierarchy and `@file.md` imports | `references/gemini-md.md` |67| Add extra include directories | `--include-directories` flag |68| Settings.json schema | `references/settings-schema.md` |6970### Hooks (migrated from Claude Code)7172| Task | Read |73|---|---|74| Migrate Claude Code hooks to Gemini | `references/hooks.md` (`gemini hooks migrate`) |75| Limitations and live-compat semantics | `references/hooks.md` (Limitations section) |7677### MCP servers7879| Task | Read |80|---|---|81| Add a stdio or http MCP server | `gemini mcp add <name> <commandOrUrl> [args...]` (see `references/mcp.md`) |82| List, enable, disable, remove MCP servers | `gemini mcp {list,enable,disable,remove}` |83| Restrict to specific MCP servers per invocation | `--allowed-mcp-server-names` |84| Use in `~/.gemini/settings.json` | `references/settings-schema.md` |85| Already-installed example | `references/mcp.md` (`nanobanana` extension example) |8687### A2A and ACP8889| Task | Read |90|---|---|91| Run Gemini CLI as an A2A server | `references/a2a-and-acp.md` (A2A section — `@google/gemini-cli-a2a-server@0.36.0` verified GA) |92| Run Gemini CLI as an ACP server (e.g. for Zed editor) | `references/a2a-and-acp.md` (ACP section — `--acp` flag) |93| Difference between A2A, ACP, and MCP | `references/a2a-and-acp.md` (Three protocols section) |9495### Authentication9697| Task | Read |98|---|---|99| OAuth personal account (default) | `references/auth.md` (OAuth section — `gemini auth login`) |100| Direct API key | `references/auth.md` (`GEMINI_API_KEY`) |101| Vertex AI via ADC | `references/auth.md` (Vertex section — `GOOGLE_GENAI_USE_VERTEXAI=1`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, `gcloud auth application-default login`) |102| Service account JSON | `references/auth.md` (`GOOGLE_APPLICATION_CREDENTIALS=<path.json>`) |103| Auth decision table | `references/auth.md` (Decision table section) |104105### Verification106107Run `scripts/verify-gemini-install.sh` after a `gemini` upgrade. The script:1081091. Captures `gemini --version`, `gemini --help`, `gemini skills --help`, `gemini extensions --help`, `gemini hooks --help`, `gemini mcp --help`1102. Lists `gemini skills list --all` and `gemini extensions list`1113. Verifies `gemini hooks migrate` subcommand still exists1124. Checks `~/.gemini/settings.json` parses as JSON if present1135. Reports auth state hint114115## Top-level subcommands (verified)116117```118mcp Manage MCP servers (add | remove | list | enable | disable)119extensions Manage extensions (install | uninstall | list | update | enable | disable | link | new | validate | config)120skills Manage agent skills (list | enable | disable | install | link | uninstall)121hooks Manage hooks — only one subcommand: migrate (one-shot import from Claude Code)122[query..] Default — launches interactive mode unless -p/--prompt is set123```124125`gemini extensions` and `gemini extension` are aliases. Same for `gemini skills` / `gemini skill`. Same for `gemini hooks` / `gemini hook`.126127## Host directive (verified 2026-05-04)128129**Canonical pattern for any headless gemini call on this host:**130131```bash132GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -p "<prompt>"133```134135- Empty env prefix forces OAuth subscription routing (otherwise `GOOGLE_CLOUD_PROJECT=thecpuwebwoov01` inherits in and 403s).136- `-m gemini-3.1-pro-preview` requests top-tier — silently downgrades to lower tier on capacity exhaustion or routing decisions, but pin it anyway to express intent.137- Model self-identification is unreliable (a model asked "what model are you?" may return the CLI name, the wrong model id, or a sibling). When the served model matters, append a `served_by=<model_id>` probe line to the prompt and capture it in the output.138- Verdict / output quality varies by served tier (verified: same ballot prompt returned different verdicts on `gemini-2.5-pro` vs `gemini-3.1-pro-preview`). Record served_by in any deliberation artifact.139140## Headless (`-p`) cheat sheet141142```bash143# Canonical (always do this on this host)144GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -p "summarize this file" < notes.md145146# JSON output147GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -p --output-format json "list TODOs in this repo"148149# Hybrid: run a prompt then drop into interactive150GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -i "investigate this bug" --include-directories ./src151152# Auto-approve all (YOLO) — sandbox + non-interactive153GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -p -y -s "refactor this function"154155# Read-only plan mode156GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -p --approval-mode plan "what would you change in this file?"157158# Restrict via Policy Engine159GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -p --policy ./ci-readonly.policy "review this PR"160161# Pin specific extensions162GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -p -e my-skill -e nanobanana "build a thumbnail for this post"163164# Resume the most recent session165GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY= gemini -m gemini-3.1-pro-preview -r latest "continue where we left off"166```167168See `references/headless.md` for the full surface and `references/policy-engine.md` for policy file format.169170## Approval modes (verified)171172| Mode | Behaviour |173|---|---|174| `default` | Prompt for approval on each tool use |175| `auto_edit` | Auto-approve edit tools, prompt for everything else |176| `yolo` | Auto-approve all tools (also via `-y`) |177| `plan` | Read-only mode |178179## Anti-patterns180181| Don't | Why |182|---|---|183| Add fields to skill frontmatter beyond `name` and `description` | Gemini silently rejects extras. Verified from built-in `skill-creator/SKILL.md`: *"Do not include any other fields in YAML frontmatter."* |184| Use `--allowed-tools` | DEPRECATED. Use the Policy Engine (`--policy`, `--admin-policy`). The flag still works but throws a deprecation warning. |185| Expect `gemini skills install` to update the symlink that bob created | `install` will likely replace symlinks with real directories. Use `gemini skills link <path>` for in-place dev. Canonical source stays in `~/.claude/skills/`. |186| Treat A2A and ACP as the same thing | A2A is agent-to-agent (`@google/gemini-cli-a2a-server`). ACP is the Agent Client Protocol — Gemini CLI acts as an ACP server for clients like Zed. Different protocols. |187| Expect `gemini hooks migrate` to keep migrated hooks in sync | One-shot import. Treat the output as a generated artifact. Re-run after editing source hooks. |188| Skip the JSON parse check on `~/.gemini/settings.json` | Malformed JSON silently breaks Gemini config loading. Run the verify script. |189| Put all skills under `~/.gemini/skills/` and forget about Claude | Canonical location is `~/.claude/skills/<name>/`. Symlink to `~/.gemini/skills/<name>/` and run `gemini skills link <path>`. See `cross-tool-portability/install-matrix.md`. |190| Use `--raw-output` without `--accept-raw-output-risk` | Disables sanitization of model output, allows ANSI escapes. Security risk if model output is untrusted. |191| Trust model self-ID for "which model answered me?" | Verified 2026-05-04: model self-ID is unreliable on this CLI — same prompt asking "what model are you?" returned `gemini-cli` (the CLI name) on one run and `gemini-2.5-pro` on another, when the actual served model was different. Capture `served_by` at the call layer with a structured probe line, not from the model's free-text answer. |192| Assume `-m <model>` deterministically picks that model | Verified 2026-05-04: requesting `-m gemini-2.5-pro` was actually served by `gemini-3.1-pro-preview` after settings.json updates. The `-m` flag is advisory; settings.json + server-side routing dominates. Always capture served_by; never assume what was asked == what was served. |193| Drop the `GOOGLE_CLOUD_PROJECT= GEMINI_API_KEY=` env prefix on this host | Shell sets `GOOGLE_CLOUD_PROJECT=thecpuwebwoov01` for vertex-banana / GA tooling. Without the empty overrides, `gemini -p` fails 403 from `cloudcode-pa.googleapis.com` even with valid OAuth creds. |194195## See also196197- `references/skills-and-extensions.md` — verified Gemini skill format from local built-in198- `references/hooks.md` — `gemini hooks migrate` semantics199- `references/policy-engine.md` — what replaced `--allowed-tools`200- `references/a2a-and-acp.md` — A2A GA confirmation, ACP --acp flag201- `references/auth.md` — 4 auth flows, decision table202- `references/settings-schema.md` — `~/.gemini/settings.json` structure (Gemini-research only — unverified)203- `references/gemini-md.md` — GEMINI.md hierarchy, imports204- `references/mcp.md` — `gemini mcp` subcommands, nanobanana example205- `claude-code-cli` — Claude Code CLI counterpart206- `gh-copilot-cli` — GitHub Copilot CLI counterpart207- `gcp-workstations` — Vertex auth on a GCP Workstation208- `research-for-skills/cross-tool-portability/` — rules for skills that span multiple CLIs209- `codex-orchestration` — Gemini MCP integration patterns210211---212> Source: [joogy06/agent-foundry](https://github.com/joogy06/agent-foundry) — distributed by [TomeVault](https://tomevault.io).213<!-- tomevault:4.0:skill_md:2026-05-23 -->
tomevault-io