Gemini CLI Provider

The ai-sdk-provider-gemini-cli community provider enables using Google's Gemini models through the @google/gemini-cli-core library and Google Cloud Code endpoints. While it works with both Gemini Code Assist (GCA) licenses and API key authentication, it's particularly useful for developers who want to use their existing GCA subscription rather than paid use API keys.

Version Compatibility

The Gemini CLI provider supports both AI SDK v4 and v5-beta:

Setup

The Gemini CLI provider is available in the ai-sdk-provider-gemini-cli module. Install the version that matches your AI SDK version:

For AI SDK v5-beta (latest)

pnpm add ai-sdk-provider-gemini-cli@beta ai@beta

For AI SDK v4 (stable)

pnpm add ai-sdk-provider-gemini-cli@^0 ai@^4

Provider Instance

You can import createGeminiProvider from ai-sdk-provider-gemini-cli and create a provider instance with your settings:

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

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

// API key authentication
const gemini = createGeminiProvider({
  authType: 'api-key',
  apiKey: process.env.GEMINI_API_KEY,
});

You can use the following settings to customize the Gemini CLI provider instance:

• authType 'oauth-personal' | 'api-key' | 'gemini-api-key'

  Required. The authentication method to use.

  • 'oauth-personal': Uses existing Gemini CLI credentials from ~/.gemini/oauth_creds.json
  • 'api-key': Standard AI SDK API key authentication (recommended)
  • 'gemini-api-key': Gemini-specific API key authentication (identical to 'api-key')

  Note: 'api-key' and 'gemini-api-key' are functionally identical. We recommend using 'api-key' for consistency with AI SDK standards, but both options map to the same Gemini authentication method internally.

• apiKey string

  Required when using API key authentication. Your Gemini API key from Google AI Studio.

Language Models

You can create models that call Gemini through the CLI using the provider instance. The first argument is the model ID:

const model = gemini('gemini-2.5-pro');

Gemini CLI supports the following models:

• gemini-2.5-pro: Most capable model for complex tasks (64K output tokens)
• gemini-2.5-flash: Faster model for simpler tasks (64K output tokens)

Example: Generate Text

You can use Gemini CLI language models to generate text with the generateText function:

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

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

// AI SDK v4
const { text } = await generateText({
  model: gemini('gemini-2.5-pro'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

// AI SDK v5-beta
const result = await generateText({
  model: gemini('gemini-2.5-pro'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});
console.log(result.content[0].text);

Gemini CLI language models can also be used in the streamText, generateObject, and streamObject functions (see AI SDK Core for more information).

Model Capabilities

Authentication

The Gemini CLI provider supports two authentication methods:

OAuth Authentication (Recommended)

First, install and authenticate the Gemini CLI globally:

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

Then use OAuth authentication in your code:

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

This uses your existing Gemini CLI credentials from ~/.gemini/oauth_creds.json.

API Key Authentication

1. Generate an API key from Google AI Studio.

2. Set it as an environment variable in your terminal:

   export GEMINI_API_KEY="YOUR_API_KEY"

   Replace YOUR_API_KEY with your generated key.

3. Use API key authentication in your code:

const gemini = createGeminiProvider({
  authType: 'api-key',
  apiKey: process.env.GEMINI_API_KEY,
});

Features

Structured Object Generation

Generate structured data using Zod schemas:

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);

Streaming Responses

Stream text for real-time output:

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',
});

// Both v4 and v5 use the same streaming API
for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

For more examples and features, including tool usage and multimodal input, see the provider documentation.

Model Parameters

You can configure model behavior with standard AI SDK parameters:

// AI SDK v4
const model = gemini('gemini-2.5-pro', {
  temperature: 0.7, // Controls randomness (0-2)
  maxTokens: 1000, // Maximum output tokens (defaults to 65536)
  topP: 0.95, // Nucleus sampling threshold
});

// AI SDK v5-beta
const model = gemini('gemini-2.5-pro', {
  temperature: 0.7, // Controls randomness (0-2)
  maxOutputTokens: 1000, // Maximum output tokens (defaults to 65536)
  topP: 0.95, // Nucleus sampling threshold
});

Limitations

• Requires Node.js ≥ 18
• OAuth authentication requires the Gemini CLI to be installed globally
• Image URLs not supported (use base64-encoded images)
• Very strict character length constraints in schemas may be challenging
• Some AI SDK parameters not supported: frequencyPenalty, presencePenalty, seed
• Only function tools supported (no provider-defined tools)

Requirements

• Node.js 18 or higher
• Gemini CLI installed globally for OAuth authentication (npm install -g @google/gemini-cli)
• Valid Google account or Gemini API key