Developer tools

Genkit provides two key developer tools:

• A CLI for command-line operations
• A local web app, called the Developer UI, that interfaces with your Genkit app for interactive testing and development

Install the CLI

NPM

npm install -g genkit-cli

Binary (Preview)

On macOS or Linux run:

curl -sL cli.genkit.dev | bash

On Windows download the binary from: here

More details can be found at https://cli.genkit.dev

Command line interface (CLI)

The CLI supports various commands to facilitate working with Genkit projects:

• genkit start -- <command to run your code>: Start the developer UI and connect it to a running code process.
• genkit flow:run <flowName>: Run a specified flow.
• genkit eval:flow <flowName>: Evaluate a specific flow.
• genkit trace:list: List traces.
• genkit trace:get <traceId>: Get a trace by ID.

Standalone vs separate terminals

Commands that interact with your code (such as flow:run and eval:flow) require a running Genkit process. You can run these commands against an already running process in a separate terminal, or you can run them standalone by appending -- <command to run your code>.

For example, to run a flow standalone, which starts the runtime, runs the flow, and exits:

genkit flow:run myFlow -- npx tsx src/index.ts

For a full list of commands, use:

genkit --help

Genkit Developer UI

The Genkit Developer UI is a local web app that lets you interactively work with models, flows, prompts, and other elements in your Genkit project.

The Developer UI is able to identify what Genkit components you have defined in your code by attaching to a running code process.

To start the UI, run the following command:

genkit start -- <command to run your code>

The <command to run your code> will vary based on your project’s setup and the file you want to execute. Here are some examples:

# Running a Go application
genkit start -- go run .

# Running a specific Go file
genkit start -- go run main.go

After running the command, you will get an output like the following:

Telemetry API running on http://localhost:4033
Genkit Developer UI: http://localhost:4000

Open the local host address for the Genkit Developer UI in your browser to view it. You can also open it in the VS Code simple browser to view it alongside your code.

Alternatively, you can use add the -o option to the start command to automatically open the Developer UI in your default browser tab.

genkit start -o -- <command to run your code>

The Developer UI has action runners for flow, prompt, model, tool, retriever, indexer, embedder and evaluator based on the components you have defined in your code.

Alongside each trace, the Developer UI lists the log records the run produced, against the span that emitted them. Genkit’s own account of the request is there, span start and finish, the resolved generate request, each model turn, and the tool loop, and so is anything your flow logged with logger.Info(ctx, ...) and friends. Records stream from an app started with genkit start without any code change. See Local observability for the logging API and the environment variables that control it.

Here’s a quick gif tour with cats.

The trace viewer shows the spans Genkit records for flows, actions, and steps. Spans that other libraries create through OpenTelemetry, such as otelhttp, go to your OpenTelemetry backend only; see Local observability.

Run the reflection API outside dev

The CLI and the Developer UI talk to your app through the reflection API, an HTTP server that genkit.Init starts in the background. By default it runs only under GENKIT_ENV=dev, which genkit start sets, and listens on 127.0.0.1, on port 3100 or the first free port above it.

To run it in another environment, for example a staging deployment that your own tooling inspects, turn it on explicitly:

GENKIT_REFLECTION_ENABLED=true \
GENKIT_REFLECTION_HOST=0.0.0.0 \
GENKIT_REFLECTION_PORT=3100 \
GENKIT_REFLECTION_SECRET_TOKEN="$(openssl rand -hex 32)" \
./server

Variable	Effect
GENKIT_REFLECTION_ENABLED	true runs the reflection API in any environment. false turns it off, even under dev. Unset, it runs only under GENKIT_ENV=dev. Any other value makes genkit.Init panic.
GENKIT_REFLECTION_HOST	The interface to listen on. Defaults to 127.0.0.1.
GENKIT_REFLECTION_PORT	The exact port to listen on: genkit.Init panics if it cannot bind it. 0 lets the operating system pick one. Unset, the server tries 3100 and then the ports above it.
GENKIT_REFLECTION_SECRET_TOKEN	A secret that every request must send in the x-genkit-reflection-secret header. Requests without it get 401. /api/__health stays open, so health checks work without the secret.

The host, port, and secret are settings, not switches: none of them turns the reflection API on by itself. To set the port in code, use genkit.WithReflectionPort:

g := genkit.Init(ctx,
    genkit.WithPlugins(&googlegenai.GoogleAI{}),
    genkit.WithReflectionPort(3200), // Exact. 0 lets the operating system pick.
)

GENKIT_REFLECTION_PORT takes precedence over the option, and the option does not turn the reflection API on.

The reflection API runs any registered action

Anyone who can reach the reflection API can run every flow, model, and tool in your app. Outside loopback, set GENKIT_REFLECTION_SECRET_TOKEN or put the port behind your own authentication. The app logs a warning when it listens on a non-loopback address without a secret.

Under dev, the app also writes a discovery file to .genkit/runtimes/ in your project root, so that a CLI process that did not start the app, such as genkit ui:start or genkit mcp, can find it. It includes the secret when one is set, so only its owner can read it. Outside dev, no file is written.

On the CLI side, --experimental-auth makes genkit start -- go run . generate a fresh secret for the app it starts and require it on every call. To share a secret with an app you start yourself, set the same GENKIT_REFLECTION_SECRET_TOKEN for both the CLI and the app.

Analytics

The Genkit CLI and Developer UI use cookies and similar technologies from Google to deliver and enhance the quality of its services and to analyze usage. Learn more.

To opt-out of analytics, you can run the following command:

genkit config set analyticsOptOut true

You can view the current setting by running:

genkit config get analyticsOptOut