# CLI Provider Integrations in Summarize: How Claude, Codex, Gemini, and Agent Authenticate

> Discover how Summarize CLI provider integrations like Claude Codex Gemini and Agent authenticate using local executables and a hierarchical lookup for binaries and config settings.

- Repository: [Peter Steinberger/summarize](https://github.com/steipete/summarize)
- Tags: deep-dive
- Published: 2026-02-19

---

**Summarize authenticates its four CLI providers—Claude, Codex, Gemini, and Agent—by locating local executables rather than using API keys, resolving binaries through a hierarchical lookup of config settings and environment variables.**

The `steipete/summarize` repository enables local LLM inference through command-line provider integrations that operate entirely on your machine. Unlike cloud-based APIs requiring secret tokens, these CLI providers authenticate solely through the presence and accessibility of their respective binaries on your system.

## Overview of the Four CLI Providers

Summarize supports four distinct local CLI providers, each mapped to a default binary name and specific environment variable overrides:

- **Claude**: Default binary `claude`, configured via `CLAUDE_PATH` or `SUMMARIZE_CLI_CLAUDE`
- **Codex**: Default binary `codex`, configured via `CODEX_PATH` or `SUMMARIZE_CLI_CODEX`  
- **Gemini**: Default binary `gemini`, configured via `GEMINI_PATH` or `SUMMARIZE_CLI_GEMINI`
- **Agent (Cursor)**: Default binary `agent`, configured via `AGENT_PATH` or `SUMMARIZE_CLI_AGENT`

All four providers execute as local subprocesses. No API keys, tokens, or network authentication are required—the authentication mechanism is simply the successful discovery and execution of the specified binary.

## Binary Resolution and Authentication

Authentication for CLI providers in Summarize follows a strict resolution order implemented in [`src/llm/cli.ts`](https://github.com/steipete/summarize/blob/main/src/llm/cli.ts) within the `resolveCliBinary()` function. The system locates executables through the following hierarchy:

1. **Configuration file setting**: Checks `cli.<provider>.binary` in your Summarize config
2. **Provider-specific environment variable**: Looks for `CLAUDE_PATH`, `CODEX_PATH`, `GEMINI_PATH`, or `AGENT_PATH`
3. **Generic environment variable**: Falls back to `SUMMARIZE_CLI_CLAUDE`, `SUMMARIZE_CLI_CODEX`, `SUMMARIZE_CLI_GEMINI`, or `SUMMARIZE_CLI_AGENT`
4. **System PATH**: Searches for the default binary name (`claude`, `codex`, `gemini`, `agent`) in your system's executable path

If the binary cannot be located through any of these methods, Summarize raises a descriptive error via `formatMissingModelError()` in [`src/run/summary-engine.ts`](https://github.com/steipete/summarize/blob/main/src/run/summary-engine.ts), such as:

```

Claude CLI not found for model cli/claude/sonnet. Install Claude CLI or set CLAUDE_PATH.

```

The required environment identifiers `CLI_CLAUDE`, `CLI_CODEX`, `CLI_GEMINI`, and `CLI_AGENT` are defined in [`src/run/types.ts`](https://github.com/steipete/summarize/blob/main/src/run/types.ts), triggering the missing CLI logic when binary resolution fails.

## Configuration Methods

You can specify CLI provider binaries through two primary mechanisms: environment variables or the Summarize configuration file.

### Environment Variables

Set provider-specific paths to override default binary locations:

```bash
export CLAUDE_PATH="$HOME/.local/bin/claude"
export CODEX_PATH="/opt/openai/codex-cli"
export GEMINI_PATH="/usr/local/bin/gemini-cli"
export AGENT_PATH="$HOME/.cursor/agent"

```

Alternatively, use the generic naming convention:

```bash
export SUMMARIZE_CLI_GEMINI="/custom/path/to/gemini"

```

### Config File Settings

Define binary paths permanently in `~/.summarize/config.json` using the `CliConfig` structure defined in [`src/config.ts`](https://github.com/steipete/summarize/blob/main/src/config.ts):

```json
{
  "cli": {
    "claude": {
      "binary": "/usr/local/bin/claude",
      "extraArgs": ["--verbose"],
      "model": "sonnet"
    },
    "codex": {
      "binary": "/opt/codex/codex-cli"
    }
  }
}

```

The `CliProvider` type in [`src/config.ts`](https://github.com/steipete/summarize/blob/main/src/config.ts) validates these configuration entries, supporting per-provider overrides for `binary`, `extraArgs`, and `model` parameters.

## Error Handling for Missing Binaries

When a requested CLI provider binary cannot be resolved, Summarize generates user-facing errors through the `formatMissingModelError()` function in [`src/run/summary-engine.ts`](https://github.com/steipete/summarize/blob/main/src/run/summary-engine.ts). These errors explicitly state which binary is missing and which environment variable can be set to resolve the issue, as implemented in the error mapping logic that consumes the `CLI_CLAUDE`, `CLI_CODEX`, `CLI_GEMINI`, and `CLI_AGENT` constants from [`src/run/types.ts`](https://github.com/steipete/summarize/blob/main/src/run/types.ts).

## Practical Usage Examples

Configure and invoke CLI providers using the following patterns:

```bash

# Use Claude CLI with custom binary location

export CLAUDE_PATH="$HOME/.local/bin/claude"
summarize --cli claude https://example.com/video.mp4

```

```bash

# Override binary via config file for Codex

cat > ~/.summarize/config.json <<'EOF'
{
  "cli": {
    "codex": { "binary": "/opt/codex/codex-cli" }
  }
}
EOF
summarize --cli codex https://example.com/article.html

```

```bash

# Use generic environment variable for Gemini

export SUMMARIZE_CLI_GEMINI="/usr/local/bin/gemini-cli"
summarize --cli gemini https://example.com/podcast.rss

```

```bash

# Disable unavailable providers by selecting specific CLI

summarize --model auto --cli codex

```

## Core Implementation Files

The CLI provider integration relies on these key source files:

- **[`src/llm/cli.ts`](https://github.com/steipete/summarize/blob/main/src/llm/cli.ts)**: Contains `resolveCliBinary()`, which implements the four-step binary lookup and resolution logic for all providers
- **[`src/config.ts`](https://github.com/steipete/summarize/blob/main/src/config.ts)**: Defines the `CliProvider` type and `CliConfig` interface that structures per-provider `binary`, `extraArgs`, and `model` settings
- **[`src/run/types.ts`](https://github.com/steipete/summarize/blob/main/src/run/types.ts)**: Declares the required-environment constants `CLI_CLAUDE`, `CLI_CODEX`, `CLI_GEMINI`, and `CLI_AGENT` that trigger missing provider logic
- **[`src/run/summary-engine.ts`](https://github.com/steipete/summarize/blob/main/src/run/summary-engine.ts)**: Implements `formatMissingModelError()` to generate actionable error messages when binaries cannot be located

## Summary

- **No API keys required**: CLI providers authenticate through local executable presence, not secret tokens
- **Four-step resolution**: Binaries are located via config file → specific env var → generic env var → PATH
- **Provider coverage**: Supports Claude, Codex, Gemini, and Agent (Cursor) with default binary names `claude`, `codex`, `gemini`, and `agent`
- **Clear error messages**: Missing binaries trigger specific errors suggesting the correct environment variable to set
- **Flexible configuration**: Override binary paths via `~/.summarize/config.json` or environment variables like `CLAUDE_PATH` and `SUMMARIZE_CLI_CODEX`

## Frequently Asked Questions

### How do I authenticate the Claude CLI provider in Summarize?

The Claude provider requires no API key authentication. Summarize authenticates Claude by locating the `claude` executable binary through the `CLAUDE_PATH` environment variable, the generic `SUMMARIZE_CLI_CLAUDE` variable, or your system PATH. Simply ensure the Claude CLI is installed and accessible, or explicitly set `CLAUDE_PATH` to its location.

### Can I use a custom binary name for the Codex provider?

Yes. While the default binary name is `codex`, you can specify any custom path or filename through the `CODEX_PATH` environment variable, the `SUMMARIZE_CLI_CODEX` variable, or by setting `cli.codex.binary` in your `~/.summarize/config.json` file. The `resolveCliBinary()` function in [`src/llm/cli.ts`](https://github.com/steipete/summarize/blob/main/src/llm/cli.ts) processes these overrides before falling back to the default name.

### What happens if the Gemini binary is not installed?

If Summarize cannot locate the Gemini binary through any configuration method, it raises a missing CLI error via `formatMissingModelError()` in [`src/run/summary-engine.ts`](https://github.com/steipete/summarize/blob/main/src/run/summary-engine.ts). The error message specifically indicates that the Gemini CLI was not found and suggests setting `GEMINI_PATH`. You can avoid this by excluding Gemini from provider selection using `--cli` flags for other providers only.

### Are the Agent provider and Cursor the same integration?

Yes. The Agent provider in Summarize refers to the Cursor IDE's `agent` CLI tool. It uses the binary name `agent` by default and can be configured via `AGENT_PATH` or `SUMMARIZE_CLI_AGENT`. Like the other CLI providers, it requires no API authentication and executes locally as a subprocess managed by the resolution logic in [`src/llm/cli.ts`](https://github.com/steipete/summarize/blob/main/src/llm/cli.ts).