The Cartographer · 10 min mission

Tools & Commands: How You Drive Gemini CLI

Master the built-in tools, slash commands, @ file refs, and ! shell — and who calls what.

gemini-clitoolsslash-commandsshellcliFact-checked 2026-06-15
On this page
  1. Two name spaces
  2. Planning and interaction tools
  3. Slash commands you drive the CLI with
  4. @path — inject file content into a prompt
  5. !command — run a one-off shell command
  6. Restrict the tool set

Gemini CLI (@google/gemini-cli, stable v0.46.0, released 2026-06-10) runs an agent loop: the model requests a built-in tool, you approve it, the CLI runs it and returns the result, repeat. You never call a tool by name. This guide covers the tool set the model calls, the slash commands you type to drive the CLI, and the @path and !command prefixes that feed the prompt. After it you can read /tools output, restrict the tool set in settings.json, and route file content or shell output into a request.

Two name spaces

Tools are functions the model calls — read_file, run_shell_command, google_web_search. You see them in approval prompts and in /tools output, but you never type them. Slash commands are what you type to steer the program. Tool names drift between versions (text search is now grep_search, not the older search_file_content), so trust /tools over memory.

ToolFamilyWhat it doesApproval
list_directory *(ReadFolder)*File systemLists files/subdirs; arg dir_path; honors .gitignore / .geminiignoreAuto (read-only)
read_file *(ReadFile)*File systemReads one file (text, images, audio, PDF); args file_path, offset, limitAuto (read-only)
glob *(FindFiles)*File systemFinds files by pattern, newest first; respect_git_ignore default trueAuto (read-only)
grep_search *(SearchText)*File systemRegex content search; uses git grep when available; arg patternAuto (read-only)
read_many_filesFile systemReads/concatenates many files; this is what the @ syntax fires internallyAuto (read-only)
write_file *(WriteFile)*File systemCreates/overwrites a file; args file_path, contentPrompts you
replace *(Edit)*File systemIn-file edit; expects one match unless allow_multiple: truePrompts you
run_shell_commandExecutionbash -c (or powershell.exe -NoProfile -Command on Windows); sets GEMINI_CLI=1Prompts you
google_web_searchWebGoogle Search; arg query; returns a grounded summary with source linksAuto (read-only)
web_fetchWebFetches URLs in the prompt (up to 20); uses Gemini API urlContextAuto (confirms in Plan Mode)
Core built-in tools by family. Display names older docs use are in italics. The model requests these; the Approval column is the default behavior.

Planning and interaction tools

The agent has a layer of tools it calls on its own; you never type them:

  • ask_user — pauses to ask 1–4 questions of type choice, text, or yesno.
  • write_todos — session todo list, exactly one task in_progress at a time (status enum pending|in_progress|completed|cancelled|blocked); toggle the view with Ctrl+T.
  • enter_plan_mode / exit_plan_mode — flip into read-only Plan Mode; exit_plan_mode writes the finalized plan to ~/.gemini/tmp/<project>/plans/. enter_plan_mode is unavailable in YOLO mode.
  • list_mcp_resources / read_mcp_resource — read resources from connected MCP servers (read-only; serverName optional, uri required).
  • activate_skill — loads procedural expertise from .gemini/skills (arg name).
  • get_internal_docs — reads Gemini CLI's own docs/ so it answers about itself accurately.

Slash commands you drive the CLI with

Slash commands steer the program, not the conversation. There are 40-plus; /help prints the full list. Below are the ones to know on day one.

CommandWhat it does
/help (/?)Lists every command and shortcut
/tools ([desc])Lists tools the agent can call now; /tools desc adds descriptions
/statsSession statistics — /stats session (default), model, tools
/modelModel config — /model set <model-name> [--persist], /model manage
/mcpManage MCP servers — list/ls, auth, enable, disable, reload, schema, desc
/memoryManage hierarchical GEMINI.md memory — list, show, refresh
/resumeBrowse/resume sessions; checkpoints — list, save <tag>, resume <tag>, delete <tag>
/chatAlias for /resume — same session browser and checkpoint subcommands
/initAnalyzes the cwd and generates a tailored GEMINI.md
/clear (Ctrl+L)Clears the screen
/quit (/exit)Exits; --delete wipes the session history and temp files
First slash commands worth internalizing. Aliases and subcommands verified against docs/reference/commands.md.

@path — inject file content into a prompt

Prefix a path with @ to inject that file or directory's content into the prompt before it sends. It fires read_many_files internally, so it works on whole directories.

  • @README.md What is this file? — one file.
  • @src/ Summarize this code — a directory.
  • @My\ Documents/file.txt — escape spaces with a backslash.
  • A lone @ with no path passes the query through unchanged.

@ is git-aware by default: it excludes git-ignored paths (node_modules/, dist/, .git/, .env), so @. will not sweep in your secrets file. Tune this with context.fileFiltering in settings.

!command — run a one-off shell command

!ls -la or !git status runs that one command directly (bash on macOS/Linux, powershell.exe -NoProfile -Command on Windows), prints the output, and returns control to the agent. It sets GEMINI_CLI=1 in the subprocess so scripts can detect the launch context. A lone ! toggles persistent shell mode (distinct prompt and color) where every line is a shell command until you toggle back. ! commands run with your full permissions and no approval prompt — it is not a sandbox.

Three typed inputs, three jobs

`/command` — drive the CLI

Configures the program: pick a model, list tools, manage MCP, resume a session. /tools, /model set <id>, /mcp list, /stats.

Never touches your files directly.

`@path` and `!cmd` — feed the prompt

@path injects file/dir content (git-aware, via read_many_files). !cmd runs a shell command with your permissions and pipes the output back.

Both put real context and real actions into the loop.

One session, all three layers
… scroll to run this session
Inspect the toolbox with a slash command, load context with @, check state with !, then state an outcome and let the model pick its own tools.

Restrict the tool set

tools.core in settings.json is an allowlist for every built-in tool, not just the shell. Setting any value disables every tool not listed. To restrict the shell and keep file tools, list them all. Shell-specific entries take the form run_shell_command(<prefix>).

~/.gemini/settings.json — allow file tools + only git/npm shell commands
json
{
  "tools": {
    "core": [
      "read_file",
      "write_file",
      "replace",
      "glob",
      "grep_search",
      "list_directory",
      "run_shell_command(git)",
      "run_shell_command(npm)"
    ]
  }
}

Knowledge check

You set `"tools": { "core": ["run_shell_command(git)"] }` in `~/.gemini/settings.json` to limit the shell to git. The next session, the agent says it cannot read or edit files. Why?

Classify what you typed: /, @, !, or a plain prompt

Command explorer

Every built-in slash command worth knowing, grouped by what it touches. Search by name or purpose, filter by group, and pick one for the full when-to-use and the gotchas the menu never tells you.

32 commands

/status
Account & plan

Show version, model, account, and connectivity.

When: Confirm which model and auth method are active — including the classic case where a stray ANTHROPIC_API_KEY is shadowing your subscription. Works mid-response.

Availability varies by plan, platform, and version — type / in your own session to see exactly what is live for you.

Type into the box and watch it sort your input into the right layer — a slash command that drives the CLI, an @ file reference, a ! shell passthrough, or a plain request the model turns into tool calls.

First-session drill

  1. Survey the surface

    Launch gemini, run /help to list every command, then /tools to see exactly which tools the agent can call right now. Confirm names here rather than from memory.

  2. Feed context with @

    Point the agent at code: @src/ What does this module do?. @ is git-aware, so ignored files and .env stay out unless you change context.fileFiltering.

  3. Check ground truth with !

    Verify a claim with a raw shell command: !git status, !npm test. The output joins the context. A lone ! toggles persistent shell mode.

  4. Let the model pick the tools

    State the outcome in plain language and approve the actions it proposes. Keep default approval mode until you trust a workflow; widen to auto_edit (or --yolo in a sandbox) only once you know what it will do.

Reach the end and this star joins your charted sky.