Tools API
Create and manage custom tools for AI interactions. Extend Gemini CLI with powerful tools for file operations, shell commands, web requests, and more.
Built-in Tools
Ready-to-use tools available in Gemini CLI
File System Tools
Tools for reading, writing, and managing files
read_file
Read content from a file
Signature:
read_file(path: string): Promise<string>Example:
const content = await tools.read_file('./package.json');
console.log(content);write_file
Write content to a file
Signature:
write_file(path: string, content: string): Promise<void>Example:
await tools.write_file('./output.txt', 'Hello, World!');list_files
List files in a directory
Signature:
list_files(path: string): Promise<string[]>Example:
const files = await tools.list_files('./src');
console.log(files);Shell Tools
Tools for executing shell commands
run_shell_command
Execute a shell command
Signature:
run_shell_command(command: string, options?: ShellOptions): Promise<ShellResult>Example:
const result = await tools.run_shell_command('ls -la');
console.log(result.stdout);run_script
Execute a script file
Signature:
run_script(scriptPath: string, args?: string[]): Promise<ShellResult>Example:
const result = await tools.run_script('./build.sh', ['--production']);Web Tools
Tools for web requests and search
web_fetch
Fetch content from a URL
Signature:
web_fetch(url: string, options?: FetchOptions): Promise<string>Example:
const content = await tools.web_fetch('https://api.example.com/data');
console.log(content);web_search
Search the web for information
Signature:
web_search(query: string, options?: SearchOptions): Promise<SearchResult[]>Example:
const results = await tools.web_search('Gemini CLI documentation');
console.log(results);Custom Tool Development
Create your own tools to extend Gemini CLI functionality
Creating a Custom Tool
Here's a complete example of creating a custom weather tool:
import { Tool, ToolDefinition } from '@google/generative-ai-cli';
// Define a custom tool
const weatherTool: ToolDefinition = {
name: 'get_weather',
description: 'Get current weather for a location',
parameters: {
type: 'object',
properties: {
location: {
type: 'string',
description: 'The city and state, e.g. San Francisco, CA'
},
unit: {
type: 'string',
enum: ['celsius', 'fahrenheit'],
description: 'Temperature unit'
}
},
required: ['location']
},
execute: async ({ location, unit = 'fahrenheit' }) => {
// Your weather API logic here
const response = await fetch(`https://api.weather.com/v1/current?location=${location}&unit=${unit}`);
const data = await response.json();
return `Current weather in ${location}: ${data.temperature}°${unit === 'celsius' ? 'C' : 'F'}, ${data.description}`;
}
};
// Register the tool
gemini.registerTool(weatherTool);
// Use the tool in a conversation
const response = await gemini.ask("What's the weather like in New York?", {
tools: ['get_weather']
});Tool Registration & Management
Managing tools in your Gemini CLI instance
Register Tools
// Register a single tool
gemini.registerTool(myTool);
// Register multiple tools
gemini.registerTools([tool1, tool2, tool3]);
// Register from a plugin
gemini.loadPlugin('./my-tools-plugin');List & Manage Tools
// List all available tools
const tools = gemini.listTools();
// Get tool information
const toolInfo = gemini.getTool('tool_name');
// Unregister a tool
gemini.unregisterTool('tool_name');Best Practices
Guidelines for creating effective tools
Tool Design
- • Keep tools focused on a single responsibility
- • Provide clear, descriptive names and descriptions
- • Define comprehensive parameter schemas
- • Handle errors gracefully with meaningful messages
Performance
- • Implement async operations properly
- • Add timeout handling for long operations
- • Cache results when appropriate
- • Validate inputs before processing
Related Resources
Explore more about tool development and usage