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

> Learn how to use the Anthropic provider in ModLens with your existing API key. Easily configure via config file or environment variable for seamless vision analysis.

- Repository: [liustack/modlens](https://github.com/liustack/modlens)
- Tags: how-to-guide
- Published: 2026-08-25

---

**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`](https://github.com/liustack/modlens/blob/main/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`](https://github.com/liustack/modlens/blob/main/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`](https://github.com/liustack/modlens/blob/main/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`](https://github.com/liustack/modlens/blob/main/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.

```bash
modlens config set anthropic.apiKey

```

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

```json
{
  "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:

```bash
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxxxxxx"

```

When no `anthropic` entry exists in the config file, the provider in [`src/providers/anthropicApi.ts`](https://github.com/liustack/modlens/blob/main/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:

```bash

# 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`](https://github.com/liustack/modlens/blob/main/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`](https://github.com/liustack/modlens/blob/main/src/schema.ts)**, ensuring structured output.
3. **Network Dispatch** — The request posts to `<baseUrl>/v1/messages` via `apiFetch` in **[`src/net/proxy.ts`](https://github.com/liustack/modlens/blob/main/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:

```bash

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

```bash
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`](https://github.com/liustack/modlens/blob/main/src/providers/anthropicApi.ts) and registered in [`src/providers/index.ts`](https://github.com/liustack/modlens/blob/main/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`](https://github.com/liustack/modlens/blob/main/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`](https://github.com/liustack/modlens/blob/main/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.