skill-gemini-file-search-tool

What this skill does

# When to use
- Managing Gemini File Search stores and documents
- Uploading documents for RAG queries (including codebases)
- Querying stores with natural language
- Building Code-RAG systems for semantic code search

# Gemini File Search Tool Skill

## Purpose

Comprehensive guide for managing Google's fully managed RAG (Retrieval-Augmented Generation) system using the `gemini-file-search-tool` CLI. This tool eliminates the complexity of vector databases, embeddings, and retrieval infrastructure by providing a production-ready interface to Gemini File Search.

## When to Use This Skill

**Use this skill when:**
- Creating and managing Gemini File Search stores
- Uploading documents for semantic search and RAG queries
- Building Code-RAG systems (semantic code search with natural language)
- Querying document stores with natural language
- Managing upload caches and operation status
- Implementing document search in AI applications

**Do NOT use this skill for:**
- General document processing (use document-skills instead)
- File system operations (use Read/Write tools)
- Cloud infrastructure management (use AWS/GCP CLIs)

## CLI Tool: gemini-file-search-tool

Production-ready CLI and Python library for Google's Gemini File Search API, a fully managed RAG system that automatically handles document ingestion, chunking, embedding generation, and semantic retrieval with zero infrastructure overhead.

### Installation

```bash
# Clone repository
git clone https://github.com/dnvriend/gemini-file-search-tool.git
cd gemini-file-search-tool

# Install globally with uv
uv tool install .

# Verify installation
gemini-file-search-tool --help
```

### Prerequisites

**Authentication (Choose one):**

**Option 1: Gemini Developer API (Recommended for development)**
```bash
export GEMINI_API_KEY="your-api-key-here"
# Or
export GOOGLE_API_KEY="your-api-key-here"
```
Get API key from: https://aistudio.google.com/apikey

**Option 2: Vertex AI (For production)**
```bash
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
```

### Quick Start

```bash
# Create a store
gemini-file-search-tool create-store "my-docs"

# Upload documents
gemini-file-search-tool upload "*.pdf" --store "my-docs" -v

# Query with natural language
gemini-file-search-tool query "What is the main topic?" --store "my-docs" --show-cost
```

## Progressive Disclosure

<details>
<summary><strong>📖 Store Management Commands (Click to expand)</strong></summary>

### create-store - Create New Store

Create a new Gemini File Search store for document storage and RAG queries.

**Usage:**
```bash
gemini-file-search-tool create-store "STORE_NAME" [--display-name NAME] [-v]
```

**Arguments:**
- `STORE_NAME`: Store identifier (required, positional)
- `--display-name NAME`: Human-readable display name (optional)
- `-v`: Verbose logging

**Examples:**
```bash
# Create store with auto-generated display name
gemini-file-search-tool create-store "research-papers"

# Create store with custom display name
gemini-file-search-tool create-store "docs" --display-name "Project Documentation"

# Capture output for processing
gemini-file-search-tool create-store "code" | jq '.name'
```

**Output:**
```json
{
  "name": "fileSearchStores/abc123",
  "display_name": "research-papers",
  "create_time": "2025-11-20T10:30:00Z",
  "update_time": "2025-11-20T10:30:00Z"
}
```

---

### list-stores - List All Stores

List all available Gemini File Search stores with their metadata.

**Usage:**
```bash
gemini-file-search-tool list-stores [-v]
```

**Arguments:**
- `-v`: Verbose logging

**Examples:**
```bash
# List all stores
gemini-file-search-tool list-stores

# List with verbose logging
gemini-file-search-tool list-stores -v

# Filter stores with jq
gemini-file-search-tool list-stores | jq '.[] | select(.display_name | contains("docs"))'

# Count stores
gemini-file-search-tool list-stores | jq 'length'
```

**Output:**
```json
[
  {
    "name": "fileSearchStores/abc123",
    "display_name": "research-papers",
    "create_time": "2025-11-20T10:30:00Z",
    "update_time": "2025-11-20T10:30:00Z"
  }
]
```

---

### get-store - Get Store Details

Get detailed information about a specific store.

**Usage:**
```bash
gemini-file-search-tool get-store "STORE_NAME" [-v]
```

**Arguments:**
- `STORE_NAME`: Store name/ID (accepts display names, IDs, or full resource names)
- `-v`: Verbose logging

**Examples:**
```bash
# Get by display name
gemini-file-search-tool get-store "research-papers"

# Get by ID
gemini-file-search-tool get-store "abc123"

# Extract specific field
gemini-file-search-tool get-store "docs" | jq '.create_time'
```

---

### update-store - Update Store

Update a store's display name or metadata.

**Usage:**
```bash
gemini-file-search-tool update-store "STORE_NAME" --display-name "NEW_NAME" [-v]
```

**Examples:**
```bash
# Rename store
gemini-file-search-tool update-store "docs" --display-name "Production Documentation"
```

---

### delete-store - Delete Store

Delete a Gemini File Search store and all its documents.

**Usage:**
```bash
gemini-file-search-tool delete-store "STORE_NAME" [--force] [-v]
```

**Arguments:**
- `STORE_NAME`: Store to delete (required)
- `--force`: Skip confirmation prompt
- `-v`: Verbose logging

**Examples:**
```bash
# Delete with confirmation
gemini-file-search-tool delete-store "old-docs"

# Delete without confirmation
gemini-file-search-tool delete-store "temp-store" --force
```

**Note:** Shows cache statistics before deletion and automatically removes cache file after successful deletion.

</details>

<details>
<summary><strong>📁 Document Management Commands (Click to expand)</strong></summary>

### upload - Upload Documents

Upload files to a Gemini File Search store with intelligent caching, glob support, and parallel processing.

**Usage:**
```bash
gemini-file-search-tool upload FILES... --store "STORE_NAME" [OPTIONS]
```

**Arguments:**
- `FILES`: File paths or glob patterns (required, positional)
- `--store NAME`: Target store name (required)
- `--title TEXT`: Custom metadata title (optional)
- `--url URL`: Custom metadata URL (optional)
- `--max-tokens N`: Max tokens per chunk (default: 200)
- `--max-overlap N`: Max overlap tokens (default: 20)
- `--num-workers N`: Concurrent workers (default: CPU cores)
- `--skip-validation`: Skip file validation checks
- `--ignore-gitignore`: Ignore .gitignore patterns
- `--dry-run`: Preview files without uploading
- `--rebuild-cache`: Force re-upload all files
- `--no-wait`: Async upload without polling
- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE)

**Key Features:**
- **Intelligent Caching**: Automatically skips unchanged files using mtime-based optimization (O(1) check)
- **Glob Patterns**: Supports `*.pdf`, `docs/**/*.md`, `src/**/*.py`
- **Gitignore Support**: Respects `.gitignore` patterns by default
- **Parallel Processing**: Concurrent uploads with configurable workers
- **System File Filtering**: Auto-skips `__pycache__`, `.pyc`, `.DS_Store`
- **Async Mode**: Fire-and-forget uploads with `--no-wait`

**Examples:**
```bash
# Upload single file
gemini-file-search-tool upload document.pdf --store "papers"

# Upload multiple files
gemini-file-search-tool upload doc1.pdf doc2.pdf --store "papers"

# Upload with glob pattern
gemini-file-search-tool upload "*.pdf" --store "papers" -v

# Upload recursive with markdown files
gemini-file-search-tool upload "docs/**/*.md" --store "documentation" -v

# Upload codebase for Code-RAG
gemini-file-search-tool upload "src/**/*.py" --store "my-codebase" -v

# Async upload with 8 workers
gemini-file-search-tool upload "*.pdf" --store "papers" --no-wait --num-workers 8

# Dry-run to preview files
gemini-file-search-tool upload "**/*.py" --store "code" --dry-run -v

# Rebuild cache (force re-upload)
gemini-file-search-tool upload "**/*.py" --store "code" --rebuild-cache
```

**Output:**
```json
[
  {"file": "doc1.pdf", "status":