AI SDK Provider for Gemini CLI

Stable Release: This version is compatible with AI SDK v5. For AI SDK v4 support, use version 0.x.

A community provider for the Vercel AI SDK that enables using Google's Gemini models through the @google/gemini-cli-core library and Google Cloud Code endpoints.

Note: This provider includes robust compatibility measures for @google/gemini-cli-core, protecting against breaking changes in patch versions through intelligent proxy patterns and exact version pinning.

Version Compatibility

| Provider Version | AI SDK Version | NPM Tag | Status | Branch | | ---------------- | -------------- | ----------- | ------ | -------------------------------------------------------------------------------------- | | 1.x | v5 | latest | Stable | main | | 0.x | v4 | ai-sdk-v4 | Stable | ai-sdk-v4 |

Installing the Right Version

For AI SDK v5 (current, default):

npm install ai-sdk-provider-gemini-cli ai

For AI SDK v4 (legacy):

npm install ai-sdk-provider-gemini-cli@ai-sdk-v4 ai@^4.3.16

Disclaimer

This is an unofficial community provider and is not affiliated with or endorsed by Google or Vercel. By using this provider:

• You understand that your data will be sent to Google's servers through the Gemini CLI Core library
• You agree to comply with Google's Terms of Service
• You acknowledge this software is provided "as is" without warranties of any kind

Please ensure you have appropriate permissions and comply with all applicable terms when using this provider.

Features

• 🚀 Compatible with Vercel AI SDK (v4 and v5)
• ☁️ Uses Google Cloud Code endpoints (https://cloudcode-pa.googleapis.com)
• 🔄 Streaming support for real-time responses
• 🛠️ Tool/function calling capabilities
• 🖼️ Multimodal support (text and base64 images)
• 🔐 OAuth authentication using Gemini CLI credentials
• 📝 TypeScript support with full type safety
• 🎯 Structured object generation with Zod schemas
• 🐛 Comprehensive logging with verbose mode for debugging

Installation

1. Install and set up the Gemini CLI

npm install -g @google/gemini-cli
gemini  # Follow the interactive authentication setup

2. Add the provider

# For AI SDK v5 (current, default)
npm install ai-sdk-provider-gemini-cli ai

# For AI SDK v4 (legacy)
npm install ai-sdk-provider-gemini-cli@ai-sdk-v4 ai@^4.3.16

Quick Start

AI SDK v5

import { generateText } from 'ai';
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';

// Create provider with OAuth authentication
const gemini = createGeminiProvider({
  authType: 'oauth-personal',
});

const result = await generateText({
  model: gemini('gemini-3-pro-preview'),
  prompt: 'Write a haiku about coding',
});

console.log(result.content[0].text);

AI SDK v4

import { generateText } from 'ai';
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';

const gemini = createGeminiProvider({
  authType: 'oauth-personal',
});

const { text } = await generateText({
  model: gemini('gemini-3-pro-preview'),
  prompt: 'Write a haiku about coding',
});

console.log(text);

Breaking Changes in v1.x

See CHANGELOG.md for details on migrating from v0.x to v1.x.

Key changes:

• Requires AI SDK v5
• New response format with content arrays
• Updated parameter names (maxTokens → maxOutputTokens)
• New streaming API patterns
• Updated token usage properties

Documentation

• Examples - Comprehensive examples demonstrating all features
• API Reference - Technical documentation and implementation details
• Authentication Guide - Detailed authentication options
• Migration Guide - v0.x to v1.x migration guide

Examples

The examples/ directory contains comprehensive examples demonstrating all features:

Getting Started

• check-auth.mjs - Verify your authentication setup
• basic-usage.mjs - Simple text generation examples
• streaming.mjs - Real-time streaming responses
• conversation-history.mjs - Multi-turn conversations

Advanced Features

• generate-object-basic.mjs - Structured output with Zod schemas
• generate-object-nested.mjs - Complex nested data structures
• generate-object-constraints.mjs - Data validation and constraints
• system-messages.mjs - Control model behavior with system prompts
• error-handling.mjs - Robust error handling patterns

Run Examples

# First build the project
npm run build

# Check authentication
npm run example:check

# Run basic examples
npm run example:basic

# Run all tests
npm run example:test

See the examples README for detailed documentation.

Authentication

The provider uses OAuth authentication with Google Cloud Code endpoints:

OAuth Authentication (Recommended)

const gemini = createGeminiProvider({
  authType: 'oauth-personal',
});

This uses your existing Gemini CLI credentials from ~/.gemini/oauth_creds.json. To set up authentication:

# Initial setup - follow interactive prompts
gemini

# Or change auth method inside CLI with slash command
/auth

API Key Authentication

// Using AI SDK standard auth type (recommended)
const gemini = createGeminiProvider({
  authType: 'api-key',
  apiKey: process.env.GEMINI_API_KEY,
});

// Alternative: Gemini-specific auth type
const gemini = createGeminiProvider({
  authType: 'gemini-api-key',
  apiKey: process.env.GEMINI_API_KEY,
});

Get your API key from Google AI Studio and set it as an environment variable:

export GEMINI_API_KEY="your-api-key-here"

Usage Examples

Text Generation

**AI SDK v5:

import { generateText } from 'ai';
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';

const gemini = createGeminiProvider({
  authType: 'oauth-personal',
});

const result = await generateText({
  model: gemini('gemini-2.5-pro'),
  prompt: 'Explain quantum computing in simple terms',
  maxOutputTokens: 500,
});

console.log(result.content[0].text);
console.log(`Tokens used: ${result.usage?.totalTokens}`);

AI SDK v4:

const { text, usage } = await generateText({
  model: gemini('gemini-2.5-pro'),
  prompt: 'Explain quantum computing in simple terms',
  maxTokens: 500,
});

console.log(text);
console.log(`Tokens used: ${usage?.totalTokens}`);

Streaming Responses

import { streamText } from 'ai';
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';

const gemini = createGeminiProvider({
  authType: 'oauth-personal',
});

const result = await streamText({
  model: gemini('gemini-2.5-pro'),
  prompt: 'Write a story about a robot learning to paint',
});

// v5: Access text stream
for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

// v4: Same API for streaming

Object Generation (Structured Output)

import { generateObject } from 'ai';
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';
import { z } from 'zod';

const gemini = createGeminiProvider({
  authType: 'oauth-personal',
});

const result = await generateObject({
  model: gemini('gemini-2.5-pro'),
  schema: z.object({
    name: z.string().describe('Product name'),
    price: z.number().describe('Price in USD'),
    features: z.array(z.string()).describe('Key features'),
  }),
  prompt: 'Generate a laptop product listing',
});

console.log(result.object);

System Messages

**AI SDK v5:

import { generateText } from 'ai';
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';

const gemini = createGeminiProvider({
  authType: 'oauth-personal',
});

const result = await generateText({
  model: gemini('gemini-2.5-pro'),
  system: 'You are a helpful coding assistant. Always include code examples.',
  prompt: 'How do I read a file in Node.js?',
});

console.log(result.content[0].text);

AI SDK v4:

const { text } = await generateText({
  model: gemini('gemini-2.5-pro'),
  system: 'You are a helpful coding assistant. Always include code examples.',
  prompt: 'How do I read a file in Node.js?',
});

console.log(text);

Conversation History

**AI SDK v5:

const result = await generateText({
  model: gemini('gemini-2.5-pro'),
  messages: [
    { role: 'user', content: 'My name is Alice' },
    { role: 'assistant', content: 'Nice to meet you, Alice!' },
    { role: 'user', content: 'What is my name?' },
  ],
});

console.log(result.content[0].text); // Should mention "Alice"

AI SDK v4:

const { text } = await generateText({
  model: gemini('gemini-2.5-pro'),
  messages: [
    { role: 'user', content: 'My name is Alice' },
    { role: 'assistant', content: 'Nice to meet you, Alice!' },
    { role: 'user', content: 'What is my name?' },
  ],
});

console.log(text); // Should mention "Alice"

Supported Models

• gemini-3-pro-preview - Latest next-generation model with enhanced reasoning capabilities (Preview)
• gemini-2.5-pro - Previous generation production-ready model (64K output tokens)
• gemini-2.5-flash - Faster, efficient model (64K output tokens)

Note: This provider uses Google Cloud Code endpoints, which may have different model availability and rate limits than the direct Gemini API. The provider defaults to 64K output tokens to take full advantage of Gemini 2.5's capabilities.

Configuration

Model Settings

**AI SDK v5:

const model = gemini('gemini-2.5-pro', {
  // Standard AI SDK v5 parameters:
  temperature: 0.7,
  maxOutputTokens: 1000,
  topP: 0.95,
});

AI SDK v4:

const model = gemini('gemini-2.5-pro', {
  // Standard AI SDK v4 parameters:
  temperature: 0.7,
  maxTokens: 1000,
  topP: 0.95,
});

Logging Configuration

Control how the provider logs execution information, warnings, and errors. The logger supports multiple log levels and a verbose mode for detailed debugging.

Log Levels

The provider supports four log levels:

• debug: Detailed execution tracing (request/response, token usage, timing)
• info: General execution flow information (request completion, duration)
• warn: Warnings about configuration issues or unexpected behavior
• error: Error messages for failures and exceptions

Basic Configuration

import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';

// Default: logs warnings and errors to console
const gemini = createGeminiProvider({
  authType: 'oauth-personal',
});

// Disable all logging
const model = gemini('gemini-2.5-flash', {
  logger: false,
});

// Custom logger - must implement all four log levels
const customModel = gemini('gemini-2.5-flash', {
  logger: {
    debug: (message) => myLogger.debug('Gemini:', message),
    info: (message) => myLogger.info('Gemini:', message),
    warn: (message) => myLogger.warn('Gemini:', message),
    error: (message) => myLogger.error('Gemini:', message),
  },
});

Verbose Mode (Debug Logging)

Enable verbose mode to see detailed execution logs, including:

• Request/response tracing
• Message conversion details
• Token usage (input, output, total)
• Request duration and timing
• Finish reasons

Without verbose mode (default), only warn and error messages are logged. With verbose mode enabled, debug and info messages are also logged.

import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';
import { generateText } from 'ai';

const gemini = createGeminiProvider({
  authType: 'oauth-personal',
});

// Enable verbose logging for debugging
const model = gemini('gemini-2.5-flash', {
  verbose: true, // Enable debug and info logging
});

const result = await generateText({
  model,
  prompt: 'Hello!',
});

Custom Logger with Verbose Mode

const model = gemini('gemini-2.5-flash', {
  verbose: true,
  logger: {
    debug: (msg) => console.log(`[DEBUG] ${msg}`),
    info: (msg) => console.log(`[INFO] ${msg}`),
    warn: (msg) => console.warn(`[WARN] ${msg}`),
    error: (msg) => console.error(`[ERROR] ${msg}`),
  },
});

What Gets Logged in Verbose Mode

With verbose: true, you'll see detailed execution logs:

[DEBUG] Starting doGenerate request with model: gemini-2.5-flash
[DEBUG] Request mode: regular, response format: none
[DEBUG] Converted 2 messages
[DEBUG] Executing generateContent request
[INFO] Request completed - Duration: 1523ms
[DEBUG] Token usage - Input: 245, Output: 128, Total: 373
[DEBUG] Finish reason: stop

For streaming requests:

[DEBUG] Starting doStream request with model: gemini-2.5-flash
[DEBUG] Stream mode: regular, response format: none
[DEBUG] Converted 2 messages for streaming
[DEBUG] Starting generateContentStream request
[DEBUG] Stream started, processing chunks
[INFO] Stream completed - Duration: 2341ms
[DEBUG] Stream token usage - Input: 512, Output: 256, Total: 768
[DEBUG] Stream finish reason: stop
[DEBUG] Stream finalized, closing stream

Logger Options

• undefined (default): Uses console.debug, console.info, console.warn, and console.error
• false: Disables all logging
• Custom Logger object: Must implement debug, info, warn, and error methods

Provider Options

const gemini = createGeminiProvider({
  authType: 'oauth-personal',
  // Uses ~/.gemini/oauth_creds.json by default
});

Key Features

This provider uses Google's Cloud Code endpoints through the Gemini CLI Core library:

• 🔐 Secure OAuth authentication
• ☁️ Access to Google Cloud Code models
• 🚀 Core Vercel AI SDK features
• 📊 Structured output with JSON schemas
• 🔄 Streaming support for real-time responses

Limitations

• Requires Node.js ≥ 20
• OAuth authentication requires the Gemini CLI to be installed globally
• Rate limits may vary from the direct Gemini API
• Very strict character length constraints in schemas may be challenging for the model
• Image URLs not supported (use base64-encoded images)
• Some AI SDK parameters not supported: frequencyPenalty, presencePenalty, seed
• Only function tools supported (no provider-defined tools)
• Abort signals have limited support: While the provider correctly handles abort signals and throws AbortError, the underlying gemini-cli-core does not support request cancellation. This means aborted requests will continue running in the background until completion, though the provider will throw an AbortError as soon as it detects the abort signal

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

License

MIT - see LICENSE for details.