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

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 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, 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, 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:

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:

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:

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

The CliProvider type in 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. 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.

Practical Usage Examples

Configure and invoke CLI providers using the following patterns:

# Use Claude CLI with custom binary location

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

# 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

# Use generic environment variable for Gemini

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

# 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: Contains resolveCliBinary(), which implements the four-step binary lookup and resolution logic for all providers
• src/config.ts: Defines the CliProvider type and CliConfig interface that structures per-provider binary, extraArgs, and model settings
• 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: 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}