ClaudeCodeSDK.AuthChecker (claude_code_sdk v0.0.1)

View Source

Authentication checker and environment validator for Claude Code SDK.

This module provides functions to validate the authentication state and environment setup before making queries to Claude Code. It helps prevent authentication errors and provides helpful diagnostic information.

Basic Usage

# Quick boolean check
if ClaudeCodeSDK.AuthChecker.authenticated?() do
  ClaudeCodeSDK.query("Hello!")
else
  IO.puts("Please run: claude login")
end

# Full diagnostic check
diagnosis = ClaudeCodeSDK.AuthChecker.diagnose()

# Ensure ready or raise error
ClaudeCodeSDK.AuthChecker.ensure_ready!()

Authentication Methods

The Claude CLI supports multiple authentication methods:

  • Anthropic API key via claude login or ANTHROPIC_API_KEY environment variable
  • Amazon Bedrock via CLAUDE_CODE_USE_BEDROCK=1 and AWS credentials
  • Google Vertex AI via CLAUDE_CODE_USE_VERTEX=1 and GCP credentials

This module detects and validates all supported authentication methods.

Summary

Types

auth_status()
diagnosis()

Functions

auth_method_available?(method)

Checks if a specific authentication method is available.

authenticated?()

Quick boolean check for authentication status.

check_auth()

Checks authentication status and returns result tuple.

check_cli_installation()

Checks Claude CLI installation status.

diagnose()

Performs comprehensive diagnostic check of the environment.

ensure_ready!()

Ensures the environment is ready for Claude queries.

get_api_key_source()

Gets the current API key source information.

Types

auth_status()

@type auth_status() ::
  :ready | :cli_not_found | :not_authenticated | :invalid_credentials | :unknown

diagnosis()

@type diagnosis() :: %{
  cli_installed: boolean(),
  cli_version: String.t() | nil,
  cli_path: String.t() | nil,
  cli_error: String.t() | nil,
  authenticated: boolean(),
  auth_method: String.t() | nil,
  auth_info: String.t() | nil,
  auth_error: String.t() | nil,
  api_key_source: String.t() | nil,
  status: auth_status(),
  recommendations: [String.t()],
  last_checked: DateTime.t()
}

Functions

auth_method_available?(method)

@spec auth_method_available?(atom()) :: boolean()

Checks if a specific authentication method is available.

Parameters

  • method - Authentication method to check (:anthropic, :bedrock, or :vertex)

Examples

if ClaudeCodeSDK.AuthChecker.auth_method_available?(:bedrock) do
  IO.puts("AWS Bedrock authentication is configured")
end

authenticated?()

@spec authenticated?() :: boolean()

Quick boolean check for authentication status.

Returns true if Claude CLI is installed and properly authenticated, false otherwise.

Examples

if ClaudeCodeSDK.AuthChecker.authenticated?() do
  IO.puts("Ready to make queries")
else
  IO.puts("Authentication required")
end

check_auth()

@spec check_auth() :: {:ok, String.t()} | {:error, String.t()}

Checks authentication status and returns result tuple.

Returns {:ok, info} if authenticated, {:error, reason} otherwise.

Examples

case ClaudeCodeSDK.AuthChecker.check_auth() do
  {:ok, info} -> IO.puts("Authenticated: #{info}")
  {:error, reason} -> IO.puts("Auth failed: #{reason}")
end

check_cli_installation()

@spec check_cli_installation() :: {:ok, map()} | {:error, String.t()}

Checks Claude CLI installation status.

Returns {:ok, %{path: path, version: version}} if installed, {:error, reason} otherwise.

Examples

case ClaudeCodeSDK.AuthChecker.check_cli_installation() do
  {:ok, %{path: path, version: version}} -> 
    IO.puts("CLI installed at #{path}, version #{version}")
  {:error, reason} -> 
    IO.puts("CLI not found: #{reason}")
end

diagnose()

@spec diagnose() :: diagnosis()

Performs comprehensive diagnostic check of the environment.

Returns a detailed diagnosis map with information about CLI installation, authentication status, detected auth method, and recommendations.

Returns

A diagnosis/0 map containing:

  • cli_installed - Whether the Claude CLI is installed
  • cli_version - Version of the installed CLI (if available)
  • authenticated - Whether authentication is working
  • auth_method - Detected authentication method
  • api_key_source - Source of API credentials
  • status - Overall status (see auth_status/0)
  • recommendations - List of recommended actions
  • last_checked - Timestamp of this check

Examples

diagnosis = ClaudeCodeSDK.AuthChecker.diagnose()

case diagnosis.status do
  :ready ->
    IO.puts("✅ Ready to use Claude")

  :cli_not_found ->
    IO.puts("❌ Claude CLI not found")

  :not_authenticated ->
    IO.puts("❌ Not authenticated")
end

ensure_ready!()

@spec ensure_ready!() :: :ok

Ensures the environment is ready for Claude queries.

Raises an exception with helpful error message if not ready. Returns :ok if ready to proceed.

Examples

# Will raise if not ready
ClaudeCodeSDK.AuthChecker.ensure_ready!()

# Safe to make queries now
ClaudeCodeSDK.query("Hello!")

Raises

get_api_key_source()

@spec get_api_key_source() :: {:ok, String.t()} | {:error, String.t()}

Gets the current API key source information.

Returns information about where the API credentials are coming from.

Examples

case ClaudeCodeSDK.AuthChecker.get_api_key_source() do
  {:ok, "environment variable ANTHROPIC_API_KEY"} ->
    IO.puts("Using environment variable")

  {:ok, "claude login session"} ->
    IO.puts("Using stored session")

  {:error, reason} ->
    IO.puts("No valid API key: #{reason}")
end