ada doctor

Diagnose and troubleshoot CLI installation and configuration issues

The doctor command runs comprehensive system diagnostics to identify and help resolve issues with your Ada CLI installation, configuration, and environment setup.

Overview

The doctor command helps you:

Diagnose installation issues - Verify CLI installation and dependencies
Check configuration - Validate all configuration files
Test connectivity - Verify network access to Lovelace services
Verify providers - Test LLM provider connections
Check workspace - Validate workspace setup
Identify problems - Detect common configuration issues
Suggest fixes - Provide actionable solutions

All diagnostics are strongly typed and provide detailed metadata for troubleshooting.

Usage

bash

ada doctor [options]

Options

Option	Description	Default
`--verbose`	Show detailed diagnostic information	`false`
`--json`	Output results in JSON format	`false`
`--category <name>`	Run specific diagnostic category	All categories
`--fix`	Attempt to auto-fix detected issues	`false`

Interactive Examples

Complete System Check

$ ada doctor

Ada CLI Diagnostics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Running diagnostics...

Installation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ CLI Version: 1.0.0 (latest)
✓ Node.js Version: 24.0.0
✓ npm Version: 10.0.0
✓ Installation Path: /usr/local/bin/lovelace

Configuration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Config File: ~/.lovelace/config.json (valid)
✓ Config Schema: v1.0.0 (current)
✓ Workspace: personal-projects (exists)
⚠ Logs Directory: Disk space low (500MB remaining)

Authentication
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Authenticated: yes (user@example.com)
✓ Session Valid: expires in 25 days
✓ Credentials: encrypted and secure

LLM Providers
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Anthropic Claude: Connected (4 models available)
✓ OpenAI GPT: Connected (5 models available)
✗ Ollama: Cannot connect to http://localhost:11434
  → Ollama server not running
  → Run: ollama serve

Network
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Internet: Connected
✓ Lovelace API: Reachable (45ms)
✓ Agents Cloud: Reachable (52ms)
✓ Memory Platform: Reachable (48ms)

Git Integration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Git Installed: 2.42.0
✓ Current Repository: lovelace (clean)
✓ Remote: origin → github.com/user/lovelace

Registry
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Release Channel: homebrew (lovelace-cli)
✓ Package Updates: 1 update available (run: brew upgrade lovelace-cli)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Summary:
  ✓ 18 checks passed
  ⚠ 1 warning
  ✗ 1 error

Issues Detected:
  1. Ollama server not running
     → Run: ollama serve

Warnings:
  1. Logs directory low on disk space
     → Run: ada sessions clear --older-than 30

Overall Status: ⚠ Mostly Healthy (1 error, 1 warning)

Verbose Diagnostics

$ ada doctor --verbose

Ada CLI Diagnostics (Detailed)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Installation Checks
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ CLI Version
  Current: 1.0.0
  Latest: 1.0.0
  Up to date: Yes

✓ Node.js Version
  Current: v24.0.0
  Minimum Required: v20.0.0
  Status: Supported

✓ npm Version
  Current: 10.0.0
  Minimum Required: 9.0.0
  Status: Supported

✓ Installation Path
  Binary: /usr/local/bin/lovelace
  Permissions: -rwxr-xr-x
  Executable: Yes

Configuration Checks
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Config File Exists
  Path: /Users/username/.lovelace/config.json
  Size: 2.4 KB
  Last Modified: 2 hours ago
  Permissions: -rw-r--r--

✓ Config JSON Valid
  Parser: Validated successfully
  Schema Version: 1.0.0

✓ Config Schema
  Current: 1.0.0
  Expected: 1.0.0
  Match: Yes

✓ Workspace Exists
  Name: personal-projects
  Path: ~/.lovelace/workspaces/personal-projects
  Sessions: 12
  Last Used: 1 hour ago

⚠ Logs Directory
  Path: ~/.lovelace/logs/
  Size: 1.2 GB
  Disk Space: 500 MB remaining
  Warning: Low disk space
  Recommendation: Clean old logs

Authentication Checks
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Authentication Status
  Authenticated: Yes
  User: user@example.com
  Account ID: usr_abc123

✓ Session Validity
  Session ID: sess_xyz789
  Issued: 2025-10-15
  Expires: 2025-11-14
  Valid For: 25 days
  Status: Active

✓ Credentials Security
  Storage: ~/.lovelace/auth/credentials.enc
  Encryption: AES-256
  Permissions: -rw------- (secure)
  Status: Properly protected

[... detailed output continues for all categories ...]

Specific Category

$ ada doctor --category providers

LLM Provider Diagnostics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Testing Anthropic Claude...
✓ API Key: Configured
✓ Connection: Successful (234ms)
✓ Authentication: Valid
✓ Available Models:
  • claude-sonnet-4-5
  • claude-opus-4-8
  • claude-sonnet-4-6
  • claude-haiku-4-5
✓ Default Model: claude-sonnet-4-5 (available)

Testing OpenAI GPT...
✓ API Key: Configured
✓ Connection: Successful (312ms)
✓ Authentication: Valid
✓ Available Models:
  • gpt-4
  • gpt-4-turbo
  • gpt-4-32k
  • gpt-3.5-turbo
  • gpt-3.5-turbo-16k
✓ Default Model: gpt-4 (available)

Testing Ollama (Local)...
✗ Connection Failed
  Endpoint: http://localhost:11434
  Error: ECONNREFUSED
  Diagnosis: Ollama server not running

Fix:
  1. Start Ollama: ollama serve
  2. Verify port: echo $OLLAMA_HOST
  3. Check firewall settings

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Provider Summary:
  ✓ 2 providers working
  ✗ 1 provider unavailable

JSON Output

bash

$ ada doctor --json

{
  "timestamp": "2025-10-19T14:30:00.000Z",
  "version": "1.0.0",
  "categories": {
    "installation": {
      "status": "passed",
      "checks": [
        {
          "name": "CLI Version",
          "status": "passed",
          "current": "1.0.0",
          "latest": "1.0.0"
        },
        {
          "name": "Node.js Version",
          "status": "passed",
          "current": "v24.0.0",
          "minimum": "v20.0.0"
        }
      ]
    },
    "configuration": {
      "status": "warning",
      "checks": [
        {
          "name": "Config File",
          "status": "passed",
          "path": "~/.lovelace/config.json"
        },
        {
          "name": "Logs Directory",
          "status": "warning",
          "message": "Low disk space",
          "diskSpace": "500MB"
        }
      ]
    },
    "providers": {
      "status": "error",
      "checks": [
        {
          "name": "Anthropic Claude",
          "status": "passed",
          "responseTime": 234,
          "models": 4
        },
        {
          "name": "Ollama",
          "status": "error",
          "error": "ECONNREFUSED",
          "endpoint": "http://localhost:11434"
        }
      ]
    }
  },
  "summary": {
    "total": 20,
    "passed": 18,
    "warnings": 1,
    "errors": 1,
    "overall": "mostly_healthy"
  }
}

Auto-Fix Issues

$ ada doctor --fix

Ada CLI Diagnostics (with Auto-Fix)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Running diagnostics...

[Standard diagnostic output]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Auto-Fixing Issues
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Issue 1: Missing logs directory
  ✓ Created ~/.lovelace/logs/
  ✓ Set proper permissions

Issue 2: Deprecated config settings
  ✓ Migrated workspace.maxSessions → workspace.historyLimit
  ✓ Updated config schema to v1.0.0

Issue 3: Stale session cache
  ✓ Cleared expired sessions (3 removed)
  ✓ Compacted session database

Could NOT auto-fix:
  • Ollama server not running
    Manual action required: Run 'ollama serve'

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Auto-Fix Summary:
  ✓ Fixed 3 issues
  ⚠ 1 issue requires manual action

Diagnostic Categories

Installation

CLI version and update status
Node.js and npm versions
Installation path and permissions
Binary executability

Configuration

Config file existence and validity
JSON syntax and schema validation
Workspace configuration
Path permissions and disk space

Authentication

Authentication status
Session validity and expiration
Credential storage security
Permission configuration

LLM Providers

Provider connectivity
API key configuration
Available models
Response time and performance

Network

Internet connectivity
Lovelace API reachability
Agents Cloud connectivity
Memory Platform connectivity
Latency measurements

Git Integration

Git installation and version
Current repository status
Remote configuration
Working directory cleanliness

Registry

npm registry connectivity
Package version status
Update availability

Common Use Cases

Troubleshoot Installation Issues

Check if CLI is properly installed:

$ ada doctor

[Installation checks show all green]
✓ CLI properly installed

Verify Provider Setup

Test LLM provider connections:

$ ada doctor --category providers

[Shows provider status]
✗ Ollama not running
→ Solution: ollama serve

Check Before Important Operations

Verify system health before deployment:

$ ada doctor

[All checks pass]
✓ System healthy

$ ada agents deploy
[Proceed with deployment]

Diagnose Authentication Issues

Check auth problems:

$ ada doctor --category auth

✗ Session expired
→ Solution: lovelace auth login

Cleanup and Optimization

Find and fix common issues:

$ ada doctor --fix

✓ Fixed 3 issues automatically
✓ System optimized

Exit Codes

Code	Meaning
`0`	All diagnostics passed
`1`	Warnings detected
`2`	Errors detected
`3`	Critical errors (CLI unusable)

Troubleshooting

Doctor Command Fails

$ ada doctor

Error: Cannot run diagnostics
Failed to load configuration

Solution:
1. Check config file: cat ~/.lovelace/config.json
2. Validate JSON syntax
3. Reset if corrupted: lovelace config reset

Network Checks Timeout

✗ Network: Cannot reach Lovelace API
  Timeout after 30s

Solution:
1. Check internet connection
2. Verify firewall settings
3. Check proxy configuration: echo $HTTP_PROXY
4. Test manually: curl https://api.uselovelace.com/health

Provider Tests Fail

✗ Anthropic Claude: Authentication failed
  Error: Invalid API key

Solution:
1. Verify API key: lovelace config show --key providers.anthropic.apiKey
2. Reconfigure: ada setup
3. Check key validity: Visit https://console.anthropic.com/account/keys

Permission Errors

✗ Configuration: Cannot read config file
  Permission denied

Solution:
$ chmod 644 ~/.lovelace/config.json
$ ada doctor

Git Diagnostics Fail

✗ Git: Repository not clean
  5 uncommitted changes

Solution:
1. Review changes: git status
2. Commit or stash: git commit -am "message"
3. Re-run: ada doctor

Related Commands

lovelace config - View and manage configuration
ada setup - Configure providers
lovelace auth - Manage authentication

Related Guides

Troubleshooting Guide - Common issues and solutions
Getting Started - Initial setup guide

See the Command Reference for all available commands.

Lovelace Developer Portal