Skip to main content
The Gemini CLI provides a comprehensive suite of tools for interacting with the local file system. These tools enable the model to explore and modify your codebase efficiently and securely.

​
Overview

All file system tools operate within a rootDirectory (the current working directory or workspace root) for security. The CLI automatically respects .gitignore and .geminiignore files to avoid exposing irrelevant or sensitive files.

​
Available Tools

​
list_directory (ReadFolder)

Lists the names of files and subdirectories directly within a specified path.
​
dir_path
string
required
Absolute or relative path to the directory
​
ignore
array
Glob patterns to exclude from listing
​
file_filtering_options
object
Configuration for .gitignore and .geminiignore compliance
This tool only lists direct children of the specified directory. Use glob for recursive file discovery.

​
read_file (ReadFile)

Reads and returns the content of a specific file. Supports text, images, audio, and PDF.
​
file_path
string
required
Path to the file to read
​
offset
number
Start line for text files (0-based)
​
limit
number
Maximum number of lines to read
Example: 
// Read entire file
read_file({ file_path: "src/index.ts" })

// Read specific section
read_file({ file_path: "src/index.ts", offset: 10, limit: 20 })

​
write_file (WriteFile)

Writes content to a specified file, overwriting it if it exists or creating it if not.
​
file_path
string
required
Path to the file to write
​
content
string
required
Data to write to the file
This tool requires manual user approval before execution to prevent unintended data loss.

​
glob (FindFiles)

Finds files matching specific glob patterns across the workspace.
​
pattern
string
required
The glob pattern to match (e.g., "*.py", "src/**/*.js")
​
path
string
Absolute path to the directory to search within. Defaults to root directory.
​
case_sensitive
boolean
default:"false"
Whether the search should be case-sensitive
​
respect_git_ignore
boolean
default:"true"
Whether to respect .gitignore patterns
Behavior:
  • Returns absolute paths sorted by modification time (most recent first)
  • Ignores common directories like node_modules and .git by default
  • Does not require user confirmation
Example output: 
Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):
src/file1.ts
src/subdir/file2.ts
src/utils/helper.ts
src/config.ts
src/types.ts

​
grep_search (SearchText)

Searches for a regular expression pattern within file contents. Returns matching lines with file paths and line numbers.
​
pattern
string
required
Regular expression to search for (e.g., "function\\s+myFunction")
​
path
string
Absolute path to search within. Defaults to current working directory.
​
include
string
Glob pattern to filter files (e.g., "*.js", "src/**/*.{ts,tsx}")
Performance:
  • Uses git grep if available in a Git repository for maximum speed
  • Falls back to system grep or JavaScript-based search
Example output: 
Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"):
---
File: src/utils.ts
L15: export function myFunction() {
L22:   myFunction.call();
---
File: src/index.ts
L5: import { myFunction } from './utils';
---
Use specific include patterns to narrow your search and improve performance.

​
replace (Edit)

Replaces text within a file with precise string matching.
​
file_path
string
required
Path to the file to modify
​
instruction
string
required
Semantic description of the change being made
​
old_string
string
required
Exact literal text to find and replace
​
new_string
string
required
Exact literal text to replace with
​
allow_multiple
boolean
default:"false"
If true, replaces all occurrences. If false, only succeeds if exactly one occurrence is found.
This tool requires significant context around old_string to ensure it modifies the correct location. By default, it will fail if the text appears multiple times unless allow_multiple is true.
Example: 
// Replace a single occurrence
replace({
  file_path: "src/config.ts",
  instruction: "Update API endpoint URL",
  old_string: "const API_URL = 'http://localhost:3000'",
  new_string: "const API_URL = 'https://api.production.com'",
  allow_multiple: false
})

// Replace all occurrences (rename variable)
replace({
  file_path: "src/utils.ts",
  instruction: "Rename oldName to newName",
  old_string: "oldName",
  new_string: "newName",
  allow_multiple: true
})

​
Security

Trusted Folders

Learn how to manage file system access permissions using trusted folders

​
Next Steps

File Management Tutorial

Practical examples of using file system tools

Shell Commands

Execute shell commands for advanced operations

Build docs developers (and LLMs) love

Get started for freeTalk to us