AI SDK Provider for Gemini CLI

2.0.1 · active · verified Wed Apr 22

The 'ai-sdk-provider-gemini-cli' package serves as a community-developed provider for the Vercel AI SDK, enabling seamless integration with Google's Gemini large language models. Unlike direct API clients, this provider leverages the official Google Gemini CLI/SDK, specifically the '@google/gemini-cli-core' package, and utilizes Google Cloud Code endpoints. The current stable version is 2.0.1, offering full compatibility with AI SDK v6. This project maintains an active release cadence, frequently updating to support new Gemini models and AI SDK features. Key differentiators include its reliance on the robust Gemini CLI for authentication and model access, support for multimodal inputs (text, images, PDFs, audio, video), advanced tool/function calling, and native structured output with Zod schemas. It also provides specific configuration options like 'thinkingConfig' for fine-tuning reasoning levels in Gemini 3 models, and a flexible logging system. To use, developers must first globally install and authenticate the '@google/gemini-cli'.

Common errors

```
Error: Command failed: gemini generate --help
gemini: command not found
```
cause The `@google/gemini-cli` global command-line interface is not installed or not accessible in your system's PATH.

fix Run `npm install -g @google/gemini-cli` to install the Gemini CLI globally. Ensure your npm global bin directory is in your system's PATH.
```
Error: Request failed with status code 401: You must be logged in to use this command. Run 'gemini' for interactive setup.
```
cause The Gemini CLI has not been authenticated with your Google account, or the OAuth credentials have expired/are invalid.

fix Execute `gemini` in your terminal and follow the interactive prompts to authenticate your Google account via OAuth.
```
TypeError: (0, _ai_sdk__WEBPACK_IMPORTED_MODULE_0__.generateText) is not a function
```
cause This error typically indicates a CommonJS/ESM module incompatibility. The Vercel AI SDK (and this provider since v2.x) are primarily designed for ESM, while your project might be configured for CommonJS, or the import path is incorrect.

fix Ensure your `package.json` includes `"type": "module"` for ESM support. Use `import { generateText } from 'ai';` and other ESM import syntax. If using older AI SDK versions, verify your bundler configuration.
```
Error: The model 'gemini-1.5-flash-latest' does not support structured output with 'responseJsonSchema'.
```
cause You are attempting to use the `responseJsonSchema` feature (for native structured output) with a Gemini model that does not natively support it, or an older provider version that doesn't handle it gracefully.

fix Use a Gemini model explicitly listed as supporting `responseJsonSchema`, such as `gemini-3-pro-preview`. Ensure your `ai-sdk-provider-gemini-cli` version is `>=1.4.0` for native structured output support.
```
Error: Your Node.js version (18.x.x) is not supported. This package requires Node.js >= 20.
```
cause The underlying `@google/gemini-cli-core` and consequently `ai-sdk-provider-gemini-cli` (since v1.3.0) require Node.js version 20 or higher.

fix Upgrade your Node.js installation to version 20 or newer using a version manager like `nvm` (e.g., `nvm install 20 && nvm use 20`).

Warnings

breaking Version 2.0.0 introduced significant breaking changes to align with Vercel AI SDK v6. This includes changes to the provider interface (`ProviderV2` → `ProviderV3`), token usage reporting (flat → hierarchical), warning format (`unsupported-setting` → `unsupported`), method renames (`textEmbeddingModel()` → `embeddingModel()`), and the finish reason structure (string → `{ unified, raw }` object).
Fix: Review the AI SDK v6 migration guide and update your provider configuration, model calls, and token/warning handling to match the new interfaces and structures. For AI SDK v5 compatibility, install `ai-sdk-provider-gemini-cli@ai-sdk-v5`.
breaking A Node.js version of `>=20` is required since `ai-sdk-provider-gemini-cli` v1.3.0 and `gemini-cli-core` v0.16.0. Earlier Node.js versions will lead to runtime errors.
Fix: Upgrade your Node.js environment to version 20 or higher to ensure compatibility and stability.
gotcha This provider requires the `@google/gemini-cli` to be installed globally and authenticated separately before it can function. Without this setup, the provider cannot access Gemini models.
Fix: Run `npm install -g @google/gemini-cli` and then execute `gemini` in your terminal to complete the interactive authentication process.
gotcha Different major versions of `ai-sdk-provider-gemini-cli` are tied to specific major versions of the Vercel AI SDK. Version 2.x supports AI SDK v6 (NPM tag `latest`), version 1.x supports AI SDK v5 (NPM tag `ai-sdk-v5`), and version 0.x supports AI SDK v4 (NPM tag `ai-sdk-v4`).
Fix: Always install the provider with the correct NPM tag that matches your project's Vercel AI SDK version (e.g., `npm install ai-sdk-provider-gemini-cli@ai-sdk-v5 ai@^5.0.0` for AI SDK v5).
gotcha Prior to v2.0.1, when defining function tool parameter schemas, if only `properties` were provided, the `type: "object"` was not implicitly added, leading to Gemini function declaration validation errors.
Fix: Upgrade to v2.0.1 or later. If upgrading is not immediately possible, explicitly add `type: "object"` to any function tool parameter schemas that define `properties`.

Install

npm install ai-sdk-provider-gemini-cli npm
yarn add ai-sdk-provider-gemini-cli yarn
pnpm add ai-sdk-provider-gemini-cli pnpm

Imports

createGeminiProvider

wrong:

const createGeminiProvider = require('ai-sdk-provider-gemini-cli').createGeminiProvider;

correct:

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

This package primarily supports ESM. For AI SDK v6, ensure your project uses ESM.

generateText
wrong:
```
const { generateText } = require('ai');
```
correct:
```
import { generateText } from 'ai';
```
This is an import from the main Vercel AI SDK package, crucial for using the Gemini provider. AI SDK v6 is ESM-only.
ThinkingLevel
```
import { ThinkingLevel } from 'ai-sdk-provider-gemini-cli';
```
Type-safe enum for configuring 'thinkingLevel' in Gemini 3 models since v1.5.1/v2.0.0-beta.2.

Quickstart

Demonstrates basic text generation using the Gemini provider with OAuth authentication and a specific Gemini 3 model, printing a haiku.

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

async function main() {
  // Ensure @google/gemini-cli is installed globally and authenticated
  // npm install -g @google/gemini-cli
  // gemini (then follow interactive setup)

  const gemini = createGeminiProvider({
    authType: 'oauth-personal', // Uses credentials from ~/.gemini/oauth_creds.json
    // apiKey: process.env.GEMINI_API_KEY ?? '', // Alternative API key auth
  });

  try {
    const result = await generateText({
      model: gemini('gemini-3-pro-preview', {
        temperature: 0.7,
        maxOutputTokens: 50,
      }),
      prompt: 'Write a haiku about a majestic cat watching the sunrise.',
    });

    console.log('Generated Haiku:\n', result.text);
  } catch (error) {
    console.error('Error generating text:', error);
  }
}

main();

view raw JSON →