Gemini CLI native reference
Start with the Gemini CLI setup. For home configuration and ownership, see global configuration.
Rules
Rules without a directory scope go into the root GEMINI.md.
scope: services/paymentssends a rule toservices/payments/GEMINI.mdinstead.globs: tests/payments/**also adds it totests/payments/GEMINI.md.globsalone creates no directory scope.- External file filters and root selectors cannot go in directory documents with a scope. They follow
on-unsupported. - Scoped rules need any legacy
outputs.gemini.rules-fileoverride removed. - See scoped context for selector and runtime limits.
Agents
Native subagents, with automatic delegation, their own context window, @name invocation, and a /agents listing. The body is the system prompt.
- Frontmatter:
nameanddescription(required; default is the spec name), pluskind,model,temperature,max_turns,timeout_minswhen set. - Portable
maxTurnsis written asmax_turns. Amax_turnsthe spec sets wins. - Per-agent MCP servers: set
x-gemini.mcp_serverswith snake_case keys such ashttp_urlandinclude_tools. Gemini rejectsmcpServersand skips the agent, so sync renamesx-gemini.mcpServerswith a note. - Omit
toolsto inherit all tools. x-gemini.toolsreplaces the mapped list with Gemini's own names, including the wildcards*,mcp_*, andmcp_<server>_*.outputs.gemini.emit-agents-as-commands: truealso writes each agent as a<name>.tomlcommand (/name). Off, sync removes earlier generated TOML files.
The generic tools list maps to Gemini's tool names. Other names drop with a sync note, since an unknown entry would limit the subagent to a tool that does not exist.
| Generic | Gemini |
|---|---|
Read | read_file |
Write | write_file |
Edit | replace |
Glob | glob |
Grep | grep_search |
Bash | run_shell_command |
WebFetch | web_fetch |
WebSearch | google_web_search |
Skills
Native Agent Skills at .gemini/skills/<name>/SKILL.md. Bundled files are copied as they are.
- Gemini CLI also reads
.agents/skills/. It wins when a name is in both. outputs.gemini.emit-skills-as-commands: trueadds oneskill-<name>.tomlcommand per skill.
Commands
.gemini/commands/<name>.toml, the project slash-command directory. description becomes the TOML description. The body becomes prompt.
- A command and an agent can share a name.
git:commitis written as.gemini/commands/git/commit.tomland runs as/git:commit.- An agent is one file,
.gemini/agents/<name>.md. On Windows, sync refuses an agent named with a colon (path semantics).
Settings
Portable model maps to model.name. Other model options and settings stay. x-gemini keys merge in. Portable permission rules raise a sync note.
At user scope, portable voice settings write the experimental experimental.voiceMode and experimental.voice.activationMode keys. Gemini has no dictation language key.
MCP
The mcpServers map.
| Spec | Written as |
|---|---|
type: http (streamable HTTP) | httpUrl |
type: sse | url |
| Stdio | Also accepts cwd |
timeout(milliseconds),trust(skip tool-call confirmations),description,includeTools, andexcludeToolsare copied as written (configuration reference).- Import reads
httpUrlback astype: httpand a bareurlastype: sse. - OAuth options pass through
x-gemini.oauth(enabled,allowPrivateNetwork,authorizationResponseIssParameterSupported, and others). - Import keeps that object Gemini-specific, skips servers with literal OAuth credentials, and leaves credential references as references.
Hooks
The hooks map, keyed by event. Each hook has a matcher and a nested hooks array of {type: "command", command} handlers (hook reference). With builtins: [memory], a SessionStart hook adds the shared memory index to the session.
Gemini documents 11 events: BeforeTool, AfterTool, BeforeAgent, AfterAgent, Notification, SessionStart, SessionEnd, PreCompress, BeforeModel, AfterModel, BeforeToolSelection.
- Timeouts convert from seconds to milliseconds (vendor default 60000 ms).
- A
commandlist becomes separate handlers in one hook.x-gemini.sequential: trueruns them in order. descriptionis copied to each handler.x-gemini.namesets the display name,x-gemini.envthe environment. Your keys stay.- Gemini runs
commandthroughbash -c(PowerShell on Windows) and has noargs. Sync foldsargsintocommand, single-quoted (node 'guard.js').import geminireads it back as one shell-formcommand. agnostic-ai hook runtests aBeforeTool,AfterTool,BeforeAgent, orSessionStarthook before a session.
Folded args edge cases
- PowerShell reads folded args the same way unless one holds an apostrophe.
- A quoted command path with a space runs in bash but not PowerShell. Use a shell-form
commandthere. - Gemini replaces
$GEMINI_*path variables and$CLAUDE_PROJECT_DIRwith its own quoted path, even inside those quotes. Such an argument splits when the project path has a space.
Ignore
Ignore specs are joined into Older versions wrote .geminiignore (gitignore syntax), the file Gemini CLI reads. Override with outputs.gemini.ignore-file.Old .aiexclude files
.aiexclude, which Gemini CLI never reads. Sync removes a generated one.
Config keys
| Key | Default | Notes |
|---|---|---|
outputs.gemini.agents-dir | .gemini/agents | |
outputs.gemini.commands-dir | .gemini/commands | |
outputs.gemini.skills-dir | .gemini/skills | |
outputs.gemini.mcp-file | .gemini/settings.json | also holds hooks and settings |
outputs.gemini.emit-skills-as-commands | false | |
outputs.gemini.emit-agents-as-commands | false | |
outputs.gemini.rules-file | unset | writes legacy joined rules and skips instructions that point to source specs |
outputs.gemini.ignore-file | .geminiignore |
Import
import gemini reads .gemini/agents/*.md, .gemini/commands/**/*.toml, .gemini/skills/<name>/, and the MCP, hooks, and default model in .gemini/settings.json.
- Instructions: the root
GEMINI.mdgoes to.agnostic-ai/AGNOSTIC_AI.md. Only the rules block thatsyncappends becomes rules. - Nested files: a hand-written
<dir>/GEMINI.mdbecomes one rule with the whole file andscope: <dir>. It is named after the scope:api.mdforservices/api/, orservices-api.mdwhen another scope also ends inapi. - A directory with one rule syncs back unchanged. A nested file
syncwrote splits back into its rules. - Commands:
promptbecomes the body, in either documented form (triple-quoted block or single-line string).descriptionstays in frontmatter. - A file in a subfolder, such as
git/commit.toml, imports as the commandgit:commit. - Older agent-as-command files and the
emit-*-as-commandscopies import too, and sync back unchanged. - Hooks: nested hooks keep commands, matchers, names, descriptions, environment maps, timeouts, and sequential groups. Hooks with the same command and matcher import separately.
- A single handler's whole-second timeout imports in seconds. Otherwise
x-gemini.timeoutkeeps the native milliseconds. - Multiple handlers stay together under
x-gemini.hooks, which replacescommandfor Gemini. - Old flat hook files still import.