{"id":16940,"library":"ai-sdk-provider-gemini-cli","title":"AI SDK Provider for Gemini CLI","description":"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'.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/ben-vargas/ai-sdk-provider-gemini-cli","tags":["javascript","ai","vercel","ai-sdk","provider","gemini","google","gemini-cli","language-model","typescript"],"install":[{"cmd":"npm install ai-sdk-provider-gemini-cli","lang":"bash","label":"npm"},{"cmd":"yarn add ai-sdk-provider-gemini-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add ai-sdk-provider-gemini-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for structured output functionality, particularly when defining response schemas.","package":"zod","optional":false},{"reason":"Core dependency providing the common interface for AI SDK providers. Version ^3.0 is required for ai-sdk-provider-gemini-cli v2.x.","package":"@ai-sdk/provider","optional":false},{"reason":"The main Vercel AI SDK package. While not a direct dependency of the provider, it is essential for utilizing the provider's functionality (e.g., `generateText`).","package":"ai","optional":false}],"imports":[{"note":"This package primarily supports ESM. For AI SDK v6, ensure your project uses ESM.","wrong":"const createGeminiProvider = require('ai-sdk-provider-gemini-cli').createGeminiProvider;","symbol":"createGeminiProvider","correct":"import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';"},{"note":"This is an import from the main Vercel AI SDK package, crucial for using the Gemini provider. AI SDK v6 is ESM-only.","wrong":"const { generateText } = require('ai');","symbol":"generateText","correct":"import { generateText } from 'ai';"},{"note":"Type-safe enum for configuring 'thinkingLevel' in Gemini 3 models since v1.5.1/v2.0.0-beta.2.","symbol":"ThinkingLevel","correct":"import { ThinkingLevel } from 'ai-sdk-provider-gemini-cli';"}],"quickstart":{"code":"import { generateText } from 'ai';\nimport { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';\n\nasync function main() {\n  // Ensure @google/gemini-cli is installed globally and authenticated\n  // npm install -g @google/gemini-cli\n  // gemini (then follow interactive setup)\n\n  const gemini = createGeminiProvider({\n    authType: 'oauth-personal', // Uses credentials from ~/.gemini/oauth_creds.json\n    // apiKey: process.env.GEMINI_API_KEY ?? '', // Alternative API key auth\n  });\n\n  try {\n    const result = await generateText({\n      model: gemini('gemini-3-pro-preview', {\n        temperature: 0.7,\n        maxOutputTokens: 50,\n      }),\n      prompt: 'Write a haiku about a majestic cat watching the sunrise.',\n    });\n\n    console.log('Generated Haiku:\\n', result.text);\n  } catch (error) {\n    console.error('Error generating text:', error);\n  }\n}\n\nmain();","lang":"typescript","description":"Demonstrates basic text generation using the Gemini provider with OAuth authentication and a specific Gemini 3 model, printing a haiku."},"warnings":[{"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`.","message":"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).","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade your Node.js environment to version 20 or higher to ensure compatibility and stability.","message":"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.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"Run `npm install -g @google/gemini-cli` and then execute `gemini` in your terminal to complete the interactive authentication process.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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).","message":"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`).","severity":"gotcha","affected_versions":">=0.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0 <2.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The `@google/gemini-cli` global command-line interface is not installed or not accessible in your system's PATH.","error":"Error: Command failed: gemini generate --help\ngemini: command not found"},{"fix":"Execute `gemini` in your terminal and follow the interactive prompts to authenticate your Google account via OAuth.","cause":"The Gemini CLI has not been authenticated with your Google account, or the OAuth credentials have expired/are invalid.","error":"Error: Request failed with status code 401: You must be logged in to use this command. Run 'gemini' for interactive setup."},{"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.","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.","error":"TypeError: (0, _ai_sdk__WEBPACK_IMPORTED_MODULE_0__.generateText) is not a function"},{"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.","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.","error":"Error: The model 'gemini-1.5-flash-latest' does not support structured output with 'responseJsonSchema'."},{"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`).","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.","error":"Error: Your Node.js version (18.x.x) is not supported. This package requires Node.js >= 20."}],"ecosystem":"npm","meta_description":null}