How to Use the Anthropic Provider in ModLens with an Existing API Key

ModLens accepts an existing Anthropic API key via either the ~/.modlens/config.json file (which takes precedence) or the ANTHROPIC_API_KEY environment variable, then routes vision analysis requests through the provider implementation in src/providers/anthropicApi.ts.

The ModLens CLI supports multiple vision providers through a plugin-based architecture. The Anthropic provider is registered under the canonical name anthropic (with an alias claude) and acts as an in-process API client that transforms image inputs into structured vision evidence using Claude's vision capabilities.

Provider Resolution and Configuration Precedence

When you invoke ModLens with -p anthropic, the CLI resolves the provider name through src/providers/index.ts in the function resolveProvider. This normalizes the alias and returns the VisionProvider object.

Configuration loading follows a strict hierarchy defined in src/config.ts via the resolveProviderSettings function:

• File-only precedence — If the provider appears under the providers key in ~/.modlens/config.json, all settings (API key, base URL, model, proxy) are sourced exclusively from the file. Environment variables are ignored for that provider.
• Environment fallback — If the provider is absent from the config file, the system reads ANTHROPIC_API_KEY and ANTHROPIC_BASE_URL from the environment.

Additionally, the assertNoRetiredEndpointBinding function in src/config.ts validates that file-based providers do not reference stale endpoints.

Configuring Your Anthropic API Key

Option 1: Persistent Storage in Config File (Recommended)

Store your API key securely using the built-in configuration command. This writes to ~/.modlens/config.json and ensures the key persists across sessions.

modlens config set anthropic.apiKey

The CLI prompts for hidden input and generates a configuration block:

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-xxxxxxxxxxxxxxxxxxxx"
    }
  }
}

Option 2: Environment Variable Injection

For CI/CD pipelines or temporary usage, export the key without modifying the config file:

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxxxxxx"

When no anthropic entry exists in the config file, the provider in src/providers/anthropicApi.ts automatically falls back to process.env.ANTHROPIC_API_KEY.

Option 3: Custom Base URL Configuration

To route requests through a proxy or custom endpoint, set the base URL via either method:

# Config file approach

modlens config set anthropic.baseUrl https://custom-anthropic.example.com

# Environment approach

export ANTHROPIC_BASE_URL="https://custom-anthropic.example.com"

Execution Flow and Code Path

The Anthropic provider executes vision analysis through the following chain:

1. Request Construction — The executeAnthropicApi function in src/providers/anthropicApi.ts builds the JSON payload, encodes the image (base64 for local files, URL for remote), and injects the vision prompt.
2. Tool Schema Binding — The function declares a forced tool call named report_vision_evidence using the schema defined in src/schema.ts, ensuring structured output.
3. Network Dispatch — The request posts to <baseUrl>/v1/messages via apiFetch in src/net/proxy.ts with headers x-api-key and anthropic-version.
4. Response Parsing — The provider extracts the tool_use block from the API response and returns the structured result to the CLI.

Running Vision Analysis

Execute analysis against local or remote images using the resolved provider:

# Analyze a local screenshot

modlens -i screenshot.png -p anthropic

# Analyze a remote image URL

modlens -i https://example.com/image.jpg -p anthropic

The CLI automatically handles image encoding, constructs the multimodal prompt, and outputs structured evidence conforming to VISION_RESULT_SCHEMA.

Debugging Configuration

Verify your configuration sources and masked credentials without exposing secrets:

modlens config show

This command displays whether each setting originates from file or env and confirms the provider is correctly registered.

Summary

• The Anthropic provider is implemented in src/providers/anthropicApi.ts and registered in src/providers/index.ts under the names anthropic and claude.
• Configuration follows strict file-first precedence; environment variables ANTHROPIC_API_KEY and ANTHROPIC_BASE_URL serve only as fallbacks.
• The provider sends vision requests to the /v1/messages endpoint with forced tool calling for structured output schemas.
• Use modlens config set anthropic.apiKey for persistent storage or export ANTHROPIC_API_KEY for temporary sessions.

Frequently Asked Questions

What environment variables does the Anthropic provider support?

The provider recognizes ANTHROPIC_API_KEY for authentication and ANTHROPIC_BASE_URL for custom endpoints. These are only consulted if the anthropic provider is absent from ~/.modlens/config.json.

Can I use both config file and environment variables for the same provider?

No. According to the resolution logic in src/config.ts, if the provider appears in the config file, ModLens ignores environment variables for that provider entirely. You must choose one configuration source per provider.

Which Anthropic API endpoint does ModLens call?

The provider posts to <baseUrl>/v1/messages using the x-api-key and anthropic-version headers, as implemented in the executeAnthropicApi function and dispatched through src/net/proxy.ts.

Is the API key masked when viewing configuration?

Yes. Running modlens config show displays the source of each setting (file vs environment) while masking the actual API key value to prevent accidental exposure in terminal logs.

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