> ## Documentation Index
> Fetch the complete documentation index at: https://ail.traylinx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Heartbeat Commands

> Monitor provider health, check quotas, and discover available models

## Overview

Heartbeat commands provide real-time monitoring of AI provider availability, latency, quota usage, and model discovery.

## Commands

### status

Check health status of all configured providers.

```bash theme={null}
switchAILocal heartbeat status
```

**Output:**

```
Checking provider status...

PROVIDER              STATUS     LATENCY    MODELS    MESSAGE
--------              ------     -------    ------    -------
gemini-cli            healthy    142ms      15        
claude-cli            healthy    98ms       8         
ollama                healthy    12ms       3         
switchai-api          healthy    234ms      42        
gemini-api            healthy    156ms      15        
claude-api            healthy    187ms      12        
groq                  healthy    89ms       7         
openai-compat-xyz     degraded   2341ms     5         High latency detected
```

<Info>
  The status command automatically discovers providers from your `config.yaml` and environment variables.
</Info>

### check

Check health of a specific provider.

```bash theme={null}
switchAILocal heartbeat check <provider>
```

<ParamField path="provider" type="string" required>
  Provider name to check. Available providers:

  * `gemini` - Google Gemini (CLI)
  * `claude` - Anthropic Claude (CLI)
  * `ollama` - Local Ollama instance
  * `gemini-api` - Gemini via API
  * `claude-api` - Claude via API
  * `openai` - OpenAI API
  * `groq` - Groq API
  * Custom provider names from config
</ParamField>

<CodeGroup>
  ```bash Check Ollama theme={null}
  switchAILocal heartbeat check ollama
  ```

  ```bash Check Claude CLI theme={null}
  switchAILocal heartbeat check claude
  ```

  ```bash Check Gemini API theme={null}
  switchAILocal heartbeat check gemini-api
  ```
</CodeGroup>

**Output:**

```
Checking ollama...
Status: healthy
Latency: 12ms
Metadata:
  endpoint: http://localhost:11434
  version: 0.1.29
  models_available: 3
  models:
    - llama2:latest
    - codellama:7b
    - mistral:latest
```

**Error Example:**

```
Checking ollama...
❌ Error: Failed to check provider 'ollama': connection refused

💡 Tip: Verify the provider name and ensure it's configured.
   Available providers: gemini, claude, openai, ollama
```

### quota

Display quota usage for all API-based providers.

```bash theme={null}
switchAILocal heartbeat quota
```

**Output:**

```
Checking quotas...

PROVIDER              QUOTA USED    LIMIT       RESET
--------              ----------    -----       -----
gemini-api            15,432        1,000,000   -
claude-api            8,291         500,000     -
switchai-api          142,087       10,000,000  -
groq                  1,234         60,000      -
openai                N/A           N/A         -
gemini-cli            N/A           N/A         -
claude-cli            N/A           N/A         -
ollama                N/A           N/A         -

💡 Note: Quota information is only available for API-based providers.
   CLI-based providers (gemini-cli, claude-cli) don't report quotas.
```

<Note>
  Quota information is extracted from API response headers during health checks. Values represent token usage or request counts depending on the provider.
</Note>

### discover

Force model discovery for local providers.

```bash theme={null}
switchAILocal heartbeat discover
```

**Output:**

```
Discovering models...
✓ Discovered 3 models for ollama

Found 3 models:
  - llama2:latest (3.8 GB)
  - codellama:7b (3.8 GB)
  - mistral:latest (4.1 GB)
```

**No Models:**

```
Discovering models...
No models found.

💡 Tip: Pull some models first:
   ollama pull llama2
   ollama pull codellama
```

**Error:**

```
Discovering models...
❌ Error: Failed to discover Ollama models: connection refused

💡 Tip: Ensure Ollama is running on http://localhost:11434
   Start Ollama with: ollama serve
```

<Warning>
  Model discovery requires the memory system to be initialized:

  ```bash theme={null}
  switchAILocal memory init
  ```
</Warning>

## Provider Types

Heartbeat monitors three types of providers:

### CLI-Based Providers

* **gemini-cli** - Google Gemini via `gcloud` CLI
* **claude-cli** - Anthropic Claude via CLI

These providers don't report quotas but are checked for availability.

### API-Based Providers

* **gemini-api** - Google Gemini via REST API
* **claude-api** - Anthropic Claude via REST API
* **switchai-api** - SwitchAI proprietary API
* **groq** - Groq inference API

These providers report quota usage and rate limits.

### Local Providers

* **ollama** - Local Ollama instance
* **vibe** - Local Vibe AI

Local providers support model discovery and typically have low latency.

## Configuration

Providers are auto-registered from your `config.yaml`:

```yaml theme={null}
# Ollama local instance
ollama:
  enabled: true
  base_url: http://localhost:11434

# Gemini API keys
gemini_key:
  - api_key: AIzaSy...
    base_url: https://generativelanguage.googleapis.com/v1beta

# Claude API keys
claude_key:
  - api_key: sk-ant-...
    base_url: https://api.anthropic.com

# OpenAI-compatible providers
openai_compatibility:
  - name: groq
    base_url: https://api.groq.com/openai/v1
    api_key_entries:
      - api_key: gsk_...
```

## Environment Variable Fallbacks

If providers aren't in your config, heartbeat checks these environment variables:

```bash theme={null}
export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="AIzaSy..."
export ANTHROPIC_API_KEY="sk-ant-..."
```

## Health Check Details

<AccordionGroup>
  <Accordion title="What does 'healthy' mean?">
    A provider is marked **healthy** when:

    * Connection succeeds within 5 seconds
    * Authentication is valid
    * At least one model is available
    * Latency is under 3 seconds
  </Accordion>

  <Accordion title="What does 'degraded' mean?">
    A provider is marked **degraded** when:

    * Connection succeeds but latency > 3 seconds
    * Some models unavailable
    * Quota approaching limits

    Degraded providers remain usable but may have performance issues.
  </Accordion>

  <Accordion title="What does 'unavailable' mean?">
    A provider is marked **unavailable** when:

    * Connection fails
    * Authentication fails
    * No models available
    * Quota exceeded
  </Accordion>
</AccordionGroup>

## Status Interpretation

<CardGroup cols={2}>
  <Card title="healthy" icon="circle-check" color="#10b981">
    All systems operational. Provider ready for requests.
  </Card>

  <Card title="degraded" icon="triangle-exclamation" color="#f59e0b">
    Provider functional but experiencing issues. Fallback recommended.
  </Card>

  <Card title="unavailable" icon="circle-xmark" color="#ef4444">
    Provider offline or inaccessible. Requests will fail.
  </Card>

  <Card title="unknown" icon="circle-question" color="#6b7280">
    Provider not yet checked or check timed out.
  </Card>
</CardGroup>

## Steering and Hooks Integration

Heartbeat status can trigger automated responses:

### Steering Rules

Automatically route around unhealthy providers:

```yaml theme={null}
# ~/.switchailocal/steering/fallback-unhealthy.yaml
name: "Fallback on Provider Failure"
activation:
  condition: "provider_status == 'unavailable'"
  priority: 100
preferences:
  primary_model: "claude-sonnet-4"
  fallback_providers:
    - anthropic
    - google
    - openai
```

### Hooks

Receive alerts when providers become unhealthy:

```yaml theme={null}
# ~/.switchailocal/hooks/health-alert.yaml
id: health-recovery
name: "Health Check Recovery"
enabled: true
event: health_check_failed
condition: "data.provider == 'ollama'"
action: restart_provider
params:
  max_retries: 3
  retry_delay: 5s
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="No providers registered">
    Providers are auto-registered from config:

    1. Check your `config.yaml` has provider sections
    2. Verify API keys are set (not placeholders)
    3. Set environment variables as fallback:

    ```bash theme={null}
    export OPENAI_API_KEY="sk-..."
    export GEMINI_API_KEY="AIzaSy..."
    ```
  </Accordion>

  <Accordion title="Ollama shows as unavailable">
    Ensure Ollama is running:

    ```bash theme={null}
    # Start Ollama
    ollama serve

    # Verify it's running
    curl http://localhost:11434/api/tags

    # Check with heartbeat
    switchAILocal heartbeat check ollama
    ```
  </Accordion>

  <Accordion title="API provider auth failed">
    Verify API keys are valid:

    ```bash theme={null}
    # Re-authenticate
    switchAILocal --claude-login
    switchAILocal --login  # Gemini

    # Or update config.yaml with valid keys
    ```
  </Accordion>

  <Accordion title="Quota information not showing">
    Quota info requires:

    1. API-based provider (not CLI)
    2. Valid authentication
    3. Provider supports quota headers

    ```bash theme={null}
    # Check quota specifically
    switchAILocal heartbeat quota
    ```
  </Accordion>
</AccordionGroup>

## Related Commands

* [Memory Commands](/cli/memory) - View routing history
* [Steering Commands](/cli/heartbeat) - Configure automatic fallbacks
* [Hooks Commands](/cli/heartbeat) - Set up health alerts