Genkit CLI

1.32.0 · active · verified Sun Apr 19

Genkit is an open-source framework by Google for building and deploying AI-powered applications, available with JavaScript/TypeScript, Go, and Python SDKs. The `genkit-cli` package provides the command-line interface for interacting with the Genkit framework, facilitating development tasks such as project initialization, running local development servers, deploying flows, and inspecting traces. The current stable version of the JavaScript/TypeScript CLI is 1.32.0, with minor updates and release candidates released frequently, indicating active development. Key differentiators include its multi-language SDK support, integration with Google's AI services (like Vertex AI and Google GenAI), and a local development UI for visualizing AI application flows and traces.

Common errors

```
genkit: command not found
```
cause The `genkit-cli` package was not installed globally, or the global npm bin directory is not in your system's PATH.

fix Run `npm install -g genkit-cli` to install the CLI globally. If the issue persists, ensure your shell's PATH includes the directory where npm installs global packages.
```
Error: listen EADDRINUSE: address already in use :::3400 (or other port)
```
cause The default port for the Genkit Developer UI (often 3400 or 4000) is already being used by another process on your system.

fix Stop the conflicting process, or specify a different port for the Genkit UI using the `--port` or `-p` option, e.g., `genkit start --port 4001 -- npx tsx src/index.ts`.
```
No Google AI API key was provided. Please pass in a valid API key through the 'apiKey' field.
```
cause The Genkit configuration (e.g., in `genkit.ts`) requires an API key for the chosen AI model provider (e.g., Google AI), but it was not provided or correctly loaded from environment variables.

fix Obtain an API key from your model provider (e.g., Google AI Studio for Gemini). Set it as an environment variable before running Genkit, for example: `export GOOGLE_API_KEY='YOUR_API_KEY'`.
```
TypeError: (0 , _core.configureGenkit) is not a function
```
cause This often indicates a module resolution issue, potentially an ESM/CommonJS conflict, or an incorrect import statement when trying to use `@genkit-ai/core` in a TypeScript/Node.js environment not correctly configured for ESM.

fix Ensure your `package.json` has `"type": "module"` and your `tsconfig.json` targets `ES2020` or higher with `"module": "NodeNext"` or `"ESNext"`. Use `npx tsx` for direct execution of TypeScript files in development, or compile to ESM and run.

Warnings

deprecated Some Imagen and Veo models were deprecated in `genkit-cli` v1.32.0 and later versions of `@genkit-ai/google-genai` plugin. Users relying on these specific models should migrate to supported alternatives.
Fix: Review the `@genkit-ai/google-genai` plugin documentation for current model availability and migrate to recommended or alternative models.
breaking The Genkit framework, particularly for Node.js/TypeScript, requires Node.js v20 or higher. Older Node.js versions (e.js., v16, v18) will result in errors and prevent `genkit-cli` from functioning correctly.
Fix: Upgrade your Node.js environment to version 20 or higher (e.g., using `nvm install 20` and `nvm use 20`).
breaking The `genkit-cli` install script `cli.genkit.dev` may serve an incorrect binary (e.g., arm64 instead of x64) on certain macOS architectures, leading to installation failures.
Fix: If `curl -sL cli.genkit.dev | bash` fails, manually download the correct binary for your architecture from the Genkit GitHub releases or use `npm install -g genkit-cli` directly.
gotcha The introduction of a new `generate` middleware and `@genkit-ai/middleware` package in `v1.33.0-rc.0` (and subsequent stable releases) may necessitate refactoring for existing users who implemented custom middleware patterns. While not strictly a breaking change in the CLI itself, it signals evolving API patterns within the Genkit ecosystem.
Fix: Consult the Genkit documentation for the new middleware package and adapt any custom middleware implementations to align with the updated patterns.

Install

npm install genkit-cli npm
yarn add genkit-cli yarn
pnpm add genkit-cli pnpm

Quickstart

This quickstart demonstrates how to install the Genkit CLI, initialize a new Genkit project, configure it with the Google AI plugin, define a simple AI flow, and then run it using the local development UI. It includes setting up environment variables for API keys and assumes a basic TypeScript project setup.

# 1. Install the Genkit CLI globally
npm install -g genkit-cli

# 2. Initialize a new Genkit project (select 'TypeScript' and a plugin like 'Google AI')
# This creates a genkit.ts config file and boilerplate.
genkit init

# 3. Configure your Genkit project and define a simple flow (e.g., in src/index.ts)
# Make sure to set environment variables like GOOGLE_API_KEY or GEMINI_API_KEY.
# For example, in a .env file or by exporting:
# export GOOGLE_API_KEY="YOUR_API_KEY"

// src/index.ts (example configuration and flow)
import { configureGenkit, defineFlow, generate, z } from '@genkit-ai/core';
import { googleGenai } from '@genkit-ai/google-genai';

export default configureGenkit({
  plugins: [
    googleGenai({ apiKey: process.env.GOOGLE_API_KEY ?? '' }),
  ],
  flowRegistry: [
    defineFlow(
      {
        name: 'helloWorldFlow',
        inputSchema: z.string().describe('Name to greet'),
        outputSchema: z.string().describe('Greeting message'),
      },
      async (name) => {
        const response = await generate({ 
          model: 'gemini-pro', 
          prompt: `Hello, ${name}! Generate a short, friendly greeting.`, 
          config: { temperature: 0.7 }
        });
        return response.text();
      }
    ),
  ],
  logLevel: 'debug',
  enableTracing: true,
});

// 4. Start the local Genkit development UI
# This command starts your app in dev mode and launches a local web UI (typically http://localhost:3400 or 4000).
# You can then interact with 'helloWorldFlow' via the UI.
genkit start -- npx tsx --watch src/index.ts

# 5. Run a flow directly from the CLI (optional)
# genkit flow:run helloWorldFlow '{"name": "Genkit User"}'

view raw JSON →