Skip to content

Commit 477ac43

Browse files
ben-vargasben-vargas
committed
docs: update Gemini CLI provider for AI SDK v6
- Add version compatibility table showing v6, v5, and v4 support - Update installation commands with correct version specifiers - Clarify authentication options (6 auth types, optional with oauth-personal default) - Move verbose/logger to model settings section - Add Gemini 3 model documentation
1 parent 4d5ac63 commit 477ac43

File tree

1 file changed

+81
-207
lines changed

1 file changed

+81
-207
lines changed

‎content/providers/03-community-providers/100-gemini-cli.mdx‎

Lines changed: 81 additions & 207 deletions
Original file line numberDiff line numberDiff line change
@@ -1,113 +1,105 @@
11
---
22
title: Gemini CLI
3-
description: Learn how to use the Gemini CLI community provider to access Google's Gemini models through the official CLI/SDK.
3+
description: Learn how to use the Gemini CLI provider to access Google's Gemini models.
44
---
55

66
# Gemini CLI Provider
77

8-
The [ai-sdk-provider-gemini-cli](https://github.com/ben-vargas/ai-sdk-provider-gemini-cli) community provider enables using Google's Gemini models through the [@google/gemini-cli-core](https://www.npmjs.com/package/@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.
8+
The [ai-sdk-provider-gemini-cli](https://github.com/ben-vargas/ai-sdk-provider-gemini-cli) community provider enables using Google's Gemini models through the [@google/gemini-cli-core](https://www.npmjs.com/package/@google/gemini-cli-core) library. It's useful for developers who want to use their existing Gemini Code Assist subscription or API key authentication.
99

1010
## Version Compatibility
1111

12-
The Gemini CLI provider supports both AI SDK v4 and v5-beta:
12+
| Provider Version | AI SDK Version | NPM Tag | Status |
13+
| ---------------- | -------------- | ----------- | ----------- |
14+
| 2.x | v6 | `latest` | Stable |
15+
| 1.x | v5 | `ai-sdk-v5` | Maintenance |
16+
| 0.x | v4 | `ai-sdk-v4` | Legacy |
1317

14-
| Provider Version | AI SDK Version | Status | Branch |
15-
| ---------------- | -------------- | ------ | -------------------------------------------------------------------------------------- |
16-
| 0.x | v4 | Stable | [`ai-sdk-v4`](https://github.com/ben-vargas/ai-sdk-provider-gemini-cli/tree/ai-sdk-v4) |
17-
| 1.x-beta | v5-beta | Beta | [`main`](https://github.com/ben-vargas/ai-sdk-provider-gemini-cli/tree/main) |
18-
19-
## Setup
20-
21-
The Gemini CLI provider is available in the `ai-sdk-provider-gemini-cli` module. Install the version that matches your AI SDK version:
22-
23-
### For AI SDK v5-beta (latest)
18+
```bash
19+
# AI SDK v6 (default)
20+
npm install ai-sdk-provider-gemini-cli ai
2421

25-
<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
26-
<Tab>
27-
<Snippet text="pnpm add ai-sdk-provider-gemini-cli ai" dark />
28-
</Tab>
29-
<Tab>
30-
<Snippet text="npm install ai-sdk-provider-gemini-cli ai" dark />
31-
</Tab>
32-
<Tab>
33-
<Snippet text="yarn add ai-sdk-provider-gemini-cli ai" dark />
34-
</Tab>
22+
# AI SDK v5
23+
npm install ai-sdk-provider-gemini-cli@ai-sdk-v5 ai@^5.0.0
3524

36-
<Tab>
37-
<Snippet text="bun add ai-sdk-provider-gemini-cli ai" dark />
38-
</Tab>
39-
</Tabs>
25+
# AI SDK v4
26+
npm install ai-sdk-provider-gemini-cli@ai-sdk-v4 ai@^4.0.0
27+
```
4028

41-
### For AI SDK v4 (stable)
29+
## Setup
4230

4331
<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
4432
<Tab>
45-
<Snippet text="pnpm add ai-sdk-provider-gemini-cli@^0 ai@^4" dark />
33+
<Snippet text="pnpm add ai-sdk-provider-gemini-cli" dark />
4634
</Tab>
4735
<Tab>
48-
<Snippet text="npm install ai-sdk-provider-gemini-cli@^0 ai@^4" dark />
36+
<Snippet text="npm install ai-sdk-provider-gemini-cli" dark />
4937
</Tab>
5038
<Tab>
51-
<Snippet text="yarn add ai-sdk-provider-gemini-cli@^0 ai@^4" dark />
39+
<Snippet text="yarn add ai-sdk-provider-gemini-cli" dark />
5240
</Tab>
53-
5441
<Tab>
55-
<Snippet text="bun add ai-sdk-provider-gemini-cli@^0 ai@^4" dark />
42+
<Snippet text="bun add ai-sdk-provider-gemini-cli" dark />
5643
</Tab>
5744
</Tabs>
5845

5946
## Provider Instance
6047

61-
You can import `createGeminiProvider` from `ai-sdk-provider-gemini-cli` and create a provider instance with your settings:
48+
Import `createGeminiProvider` and create a provider instance with your authentication settings:
6249

6350
```ts
6451
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';
6552

66-
// OAuth authentication (recommended)
67-
const gemini = createGeminiProvider({
68-
authType: 'oauth-personal',
69-
});
53+
// OAuth authentication (default if authType omitted)
54+
const gemini = createGeminiProvider({ authType: 'oauth-personal' });
7055

7156
// API key authentication
7257
const gemini = createGeminiProvider({
73-
authType: 'api-key',
58+
authType: 'api-key', // or 'gemini-api-key'
7459
apiKey: process.env.GEMINI_API_KEY,
7560
});
76-
```
77-
78-
You can use the following settings to customize the Gemini CLI provider instance:
79-
80-
- **authType** _'oauth-personal' | 'api-key' | 'gemini-api-key'_
8161

82-
Required. The authentication method to use.
83-
84-
- `'oauth-personal'`: Uses existing Gemini CLI credentials from `~/.gemini/oauth_creds.json`
85-
- `'api-key'`: Standard AI SDK API key authentication (recommended)
86-
- `'gemini-api-key'`: Gemini-specific API key authentication (identical to `'api-key'`)
62+
// Vertex AI authentication
63+
const gemini = createGeminiProvider({
64+
authType: 'vertex-ai',
65+
vertexAI: {
66+
projectId: 'my-project',
67+
location: 'us-central1',
68+
},
69+
});
8770

88-
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.
71+
// Google Auth Library
72+
const gemini = createGeminiProvider({
73+
authType: 'google-auth-library',
74+
googleAuth: myGoogleAuthInstance,
75+
});
76+
```
8977

90-
- **apiKey** _string_
78+
Authentication options:
9179

92-
Required when using API key authentication. Your Gemini API key from [Google AI Studio](https://aistudio.google.com/apikey).
80+
- **authType** _'oauth' | 'oauth-personal' | 'api-key' | 'gemini-api-key' | 'vertex-ai' | 'google-auth-library'_ - Optional. Defaults to `'oauth-personal'`.
81+
- **apiKey** _string_ - Required for `'api-key'` / `'gemini-api-key'`.
82+
- **vertexAI** _{ projectId, location }_ - Required for `'vertex-ai'`.
83+
- **googleAuth** _GoogleAuth_ - Required for `'google-auth-library'`.
84+
- **cacheDir** _string_ - Optional directory for OAuth credentials cache.
85+
- **proxy** _string_ - HTTP/HTTPS proxy URL.
9386

9487
## Language Models
9588

96-
You can create models that call Gemini through the CLI using the provider instance.
97-
The first argument is the model ID:
89+
Create models that call Gemini through the CLI using the provider instance:
9890

9991
```ts
10092
const model = gemini('gemini-2.5-pro');
10193
```
10294

103-
Gemini CLI supports the following models:
104-
105-
- **gemini-2.5-pro**: Most capable model for complex tasks (64K output tokens)
106-
- **gemini-2.5-flash**: Faster model for simpler tasks (64K output tokens)
95+
Supported models:
10796

108-
### Example: Generate Text
97+
- **gemini-3-pro-preview**: Latest model with enhanced reasoning (supports `thinkingLevel`)
98+
- **gemini-3-flash-preview**: Fast Gemini 3 model (supports `thinkingLevel`)
99+
- **gemini-2.5-pro**: Production-ready model with 64K output tokens (supports `thinkingBudget`)
100+
- **gemini-2.5-flash**: Fast, efficient model with 64K output tokens (supports `thinkingBudget`)
109101

110-
You can use Gemini CLI language models to generate text with the `generateText` function:
102+
### Example
111103

112104
```ts
113105
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';
@@ -117,182 +109,64 @@ const gemini = createGeminiProvider({
117109
authType: 'oauth-personal',
118110
});
119111

120-
// AI SDK v4
121112
const { text } = await generateText({
122113
model: gemini('gemini-2.5-pro'),
123114
prompt: 'Write a vegetarian lasagna recipe for 4 people.',
124115
});
125-
126-
// AI SDK v5-beta
127-
const result = await generateText({
128-
model: gemini('gemini-2.5-pro'),
129-
prompt: 'Write a vegetarian lasagna recipe for 4 people.',
130-
});
131-
console.log(result.content[0].text);
132116
```
133117

134-
Gemini CLI language models can also be used in the `streamText`, `generateObject`, and `streamObject` functions
135-
(see [AI SDK Core](/docs/ai-sdk-core) for more information).
118+
### Model Settings
136119

137-
<Note>
138-
The response format differs between AI SDK v4 and v5-beta. In v4, text is
139-
accessed directly via `result.text`. In v5-beta, it's accessed via
140-
`result.content[0].text`. Make sure to use the appropriate format for your AI
141-
SDK version.
142-
</Note>
120+
```ts
121+
const model = gemini('gemini-3-pro-preview', {
122+
temperature: 0.7,
123+
topP: 0.95,
124+
topK: 40,
125+
maxOutputTokens: 8192,
126+
thinkingConfig: {
127+
thinkingLevel: 'medium', // 'low' | 'medium' | 'high' | 'minimal'
128+
},
129+
verbose: true, // Enable debug logging
130+
logger: customLogger, // Custom logger (or false to disable)
131+
});
132+
```
143133

144134
### Model Capabilities
145135

146-
| Model | Image Input | Object Generation | Tool Usage | Tool Streaming |
147-
| ------------------ | ------------------- | ------------------- | ------------------- | ------------------- |
148-
| `gemini-2.5-pro` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
149-
| `gemini-2.5-flash` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
136+
| Model | Image Input | Object Generation | Tool Usage | Tool Streaming |
137+
| ------------------------ | ------------------- | ------------------- | ------------------- | ------------------- |
138+
| `gemini-3-pro-preview` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
139+
| `gemini-3-flash-preview` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
140+
| `gemini-2.5-pro` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
141+
| `gemini-2.5-flash` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
150142

151143
<Note>
152-
Images must be provided as base64-encoded data. Image URLs are not supported
153-
due to the Google Cloud Code endpoint requirements.
144+
Images must be provided as base64-encoded data. Image URLs are not supported.
154145
</Note>
155146

156147
## Authentication
157148

158-
The Gemini CLI provider supports two authentication methods:
159-
160149
### OAuth Authentication (Recommended)
161150

162-
First, install and authenticate the Gemini CLI globally:
151+
Install and authenticate the Gemini CLI globally:
163152

164153
```bash
165154
npm install -g @google/gemini-cli
166155
gemini # Follow the interactive authentication setup
167156
```
168157

169-
Then use OAuth authentication in your code:
170-
171-
```ts
172-
const gemini = createGeminiProvider({
173-
authType: 'oauth-personal',
174-
});
175-
```
176-
177-
This uses your existing Gemini CLI credentials from `~/.gemini/oauth_creds.json`.
158+
Then use OAuth authentication in your code with `authType: 'oauth-personal'`.
178159

179160
### API Key Authentication
180161

181162
1. Generate an API key from [Google AI Studio](https://aistudio.google.com/apikey).
182-
183-
2. Set it as an environment variable in your terminal:
184-
185-
```bash
186-
export GEMINI_API_KEY="YOUR_API_KEY"
187-
```
188-
189-
Replace `YOUR_API_KEY` with your generated key.
190-
191-
3. Use API key authentication in your code:
192-
193-
```ts
194-
const gemini = createGeminiProvider({
195-
authType: 'api-key',
196-
apiKey: process.env.GEMINI_API_KEY,
197-
});
198-
```
199-
200-
<Note>
201-
The Gemini API provides a free tier with 100 requests per day using Gemini 2.5
202-
Pro. You can upgrade to a paid plan for higher rate limits on the [API key
203-
page](https://aistudio.google.com/apikey).
204-
</Note>
205-
206-
## Features
207-
208-
### Structured Object Generation
209-
210-
Generate structured data using Zod schemas:
211-
212-
```ts
213-
import { generateObject } from 'ai';
214-
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';
215-
import { z } from 'zod';
216-
217-
const gemini = createGeminiProvider({
218-
authType: 'oauth-personal',
219-
});
220-
221-
const result = await generateObject({
222-
model: gemini('gemini-2.5-pro'),
223-
schema: z.object({
224-
name: z.string().describe('Product name'),
225-
price: z.number().describe('Price in USD'),
226-
features: z.array(z.string()).describe('Key features'),
227-
}),
228-
prompt: 'Generate a laptop product listing',
229-
});
230-
231-
console.log(result.object);
232-
```
233-
234-
### Streaming Responses
235-
236-
Stream text for real-time output:
237-
238-
```ts
239-
import { streamText } from 'ai';
240-
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';
241-
242-
const gemini = createGeminiProvider({
243-
authType: 'oauth-personal',
244-
});
245-
246-
const result = await streamText({
247-
model: gemini('gemini-2.5-pro'),
248-
prompt: 'Write a story about a robot learning to paint',
249-
});
250-
251-
// Both v4 and v5 use the same streaming API
252-
for await (const chunk of result.textStream) {
253-
process.stdout.write(chunk);
254-
}
255-
```
256-
257-
For more examples and features, including tool usage and multimodal input, see the [provider documentation](https://github.com/ben-vargas/ai-sdk-provider-gemini-cli).
258-
259-
## Model Parameters
260-
261-
You can configure model behavior with standard AI SDK parameters:
262-
263-
```ts
264-
// AI SDK v4
265-
const model = gemini('gemini-2.5-pro', {
266-
temperature: 0.7, // Controls randomness (0-2)
267-
maxTokens: 1000, // Maximum output tokens (defaults to 65536)
268-
topP: 0.95, // Nucleus sampling threshold
269-
});
270-
271-
// AI SDK v5-beta
272-
const model = gemini('gemini-2.5-pro', {
273-
temperature: 0.7, // Controls randomness (0-2)
274-
maxOutputTokens: 1000, // Maximum output tokens (defaults to 65536)
275-
topP: 0.95, // Nucleus sampling threshold
276-
});
277-
```
278-
279-
<Note>
280-
In AI SDK v5-beta, the `maxTokens` parameter has been renamed to
281-
`maxOutputTokens`. Make sure to use the correct parameter name for your
282-
version.
283-
</Note>
284-
285-
## Limitations
286-
287-
- Requires Node.js ≥ 18
288-
- OAuth authentication requires the Gemini CLI to be installed globally
289-
- Image URLs not supported (use base64-encoded images)
290-
- Very strict character length constraints in schemas may be challenging
291-
- Some AI SDK parameters not supported: `frequencyPenalty`, `presencePenalty`, `seed`
292-
- Only function tools supported (no provider-defined tools)
163+
2. Set it as an environment variable: `export GEMINI_API_KEY="YOUR_API_KEY"`
164+
3. Use `authType: 'api-key'` with your key.
293165

294166
## Requirements
295167

296-
- Node.js 18 or higher
297-
- Gemini CLI installed globally for OAuth authentication (`npm install -g @google/gemini-cli`)
168+
- Node.js 20 or higher
169+
- Gemini CLI installed globally for OAuth authentication
298170
- Valid Google account or Gemini API key
171+
172+
For more details, see the [provider documentation](https://github.com/ben-vargas/ai-sdk-provider-gemini-cli).

0 commit comments

Comments
 (0)