# `ClaudeAgentSDK.AuthChecker`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/auth_checker.ex#L1)

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 ClaudeAgentSDK.AuthChecker.authenticated?() do
      ClaudeAgentSDK.query("Hello!")
    else
      IO.puts("Please run: claude login")
    end

    # Full diagnostic check
    diagnosis = ClaudeAgentSDK.AuthChecker.diagnose()
    
    # Ensure ready or raise error
    ClaudeAgentSDK.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_AGENT_USE_BEDROCK=1` and AWS credentials
- Google Vertex AI via `CLAUDE_AGENT_USE_VERTEX=1` and GCP credentials

This module detects and validates all supported authentication methods.

# `auth_status`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/auth_checker.ex#L36)

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

# `diagnosis`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/auth_checker.ex#L39)

```elixir
@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()
}
```

# `auth_method_available?`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/auth_checker.ex#L280)

```elixir
@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 ClaudeAgentSDK.AuthChecker.auth_method_available?(:bedrock) do
      IO.puts("AWS Bedrock authentication is configured")
    end

# `authenticated?`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/auth_checker.ex#L70)

```elixir
@spec authenticated?() :: boolean()
```

Quick boolean check for authentication status.

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

## Examples

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

# `check_auth`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/auth_checker.ex#L231)

```elixir
@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 ClaudeAgentSDK.AuthChecker.check_auth() do
      {:ok, info} -> IO.puts("Authenticated: #{info}")
      {:error, reason} -> IO.puts("Auth failed: #{reason}")
    end

# `check_cli_installation`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/auth_checker.ex#L255)

```elixir
@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 ClaudeAgentSDK.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`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/auth_checker.ex#L112)

```elixir
@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 `t: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 `t:auth_status/0`)
- `recommendations` - List of recommended actions
- `last_checked` - Timestamp of this check

## Examples

    diagnosis = ClaudeAgentSDK.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!`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/auth_checker.ex#L182)

```elixir
@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
    ClaudeAgentSDK.AuthChecker.ensure_ready!()
    
    # Safe to make queries now
    ClaudeAgentSDK.query("Hello!")

## Raises

- `RuntimeError` - If CLI not found or authentication missing

# `get_api_key_source`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/auth_checker.ex#L316)

```elixir
@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 ClaudeAgentSDK.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

---

*Consult [api-reference.md](api-reference.md) for complete listing*