AI SDK Provider for Grok CLI

A provider for the AI SDK that integrates with Grok CLI for accessing xAI's Grok language models.

Features

✅ AI SDK v5 Compatible - Full support for the latest AI SDK interfaces
✅ Streaming & Non-streaming - Both generation modes supported
✅ Error Handling - Comprehensive error handling with retry logic
✅ Type Safety - Full TypeScript support with proper type definitions
✅ JSON Mode - Automatic JSON extraction from responses
✅ Abort Signals - Proper cancellation support

Installation

bash

npm install @tm/ai-sdk-provider-grok-cli
# or
yarn add @tm/ai-sdk-provider-grok-cli

Prerequisites

Install the Grok CLI:

bash

npm install -g grok-cli
# or follow xAI's installation instructions

Set up authentication:

bash

export GROK_CLI_API_KEY="your-api-key"
# or configure via grok CLI: grok config set api-key your-key

Usage

Basic Usage

typescript

import { grokCli } from '@tm/ai-sdk-provider-grok-cli';
import { generateText } from 'ai';

const result = await generateText({
  model: grokCli('grok-3-latest'),
  prompt: 'Write a haiku about TypeScript'
});

console.log(result.text);

Streaming

typescript

import { grokCli } from '@tm/ai-sdk-provider-grok-cli';
import { streamText } from 'ai';

const { textStream } = await streamText({
  model: grokCli('grok-4-latest'),
  prompt: 'Explain quantum computing'
});

for await (const delta of textStream) {
  process.stdout.write(delta);
}

JSON Mode

typescript

import { grokCli } from '@tm/ai-sdk-provider-grok-cli';
import { generateObject } from 'ai';
import { z } from 'zod';

const result = await generateObject({
  model: grokCli('grok-3-latest'),
  schema: z.object({
    name: z.string(),
    age: z.number(),
    hobbies: z.array(z.string())
  }),
  prompt: 'Generate a person profile'
});

console.log(result.object);

Supported Models

grok-3-latest - Grok 3 (latest version)
grok-4-latest - Grok 4 (latest version)
grok-4 - Grok 4 (stable)
Custom model strings supported

Configuration

Provider Settings

typescript

import { createGrokCli } from '@tm/ai-sdk-provider-grok-cli';

const grok = createGrokCli({
  apiKey: 'your-api-key', // Optional if set via env/CLI
  timeout: 120000, // 2 minutes default
  workingDirectory: '/path/to/project', // Optional
  baseURL: 'https://api.x.ai' // Optional
});

Model Settings

typescript

const model = grok('grok-4-latest', {
  timeout: 300000, // 5 minutes for grok-4
  // Other CLI-specific settings
});

Error Handling

The provider includes comprehensive error handling:

typescript

import {
  isAuthenticationError,
  isTimeoutError,
  isInstallationError
} from '@tm/ai-sdk-provider-grok-cli';

try {
  const result = await generateText({
    model: grokCli('grok-4-latest'),
    prompt: 'Hello!'
  });
} catch (error) {
  if (isAuthenticationError(error)) {
    console.error('Authentication failed:', error.message);
  } else if (isTimeoutError(error)) {
    console.error('Request timed out:', error.message);
  } else if (isInstallationError(error)) {
    console.error('Grok CLI not installed or not found in PATH');
  }
}

Development

bash

# Install dependencies
npm install

# Start development mode (keep running during development)
npm run dev

# Type check
npm run typecheck

# Run tests (requires build first)
NODE_ENV=production npm run build
npm test

Important: Always run npm run dev and keep it running during development. This ensures proper compilation and hot-reloading of TypeScript files.