kicad-sch-api: Command for Claude Code

Troubleshoot KiCAD Symbol Library Issues

Common Symptom

User reports errors like:

• "Library not found"
• "Symbol X:Y not found"
• "Cannot load component from library"
• Components fail to create with library errors

Root Cause

The kicad-sch-api library cannot find KiCAD symbol libraries (.kicad_sym files).

Solution: Configure Library Paths

Step 1: Find Your KiCAD Installation

✨ NEW: Automatic Library Finder

The easiest way to find your KiCAD libraries:

ksa-find-libraries

This command automatically searches your system and provides setup instructions.

Manual Search (if needed):

macOS:

ls /Applications/KiCad*.app/Contents/SharedSupport/symbols/

Linux:

ls /usr/share/kicad/symbols/
ls ~/.local/share/kicad/*/symbols/

Windows:

dir "C:\Program Files\KiCad\*\share\kicad\symbols"

Step 2: Set Environment Variable

macOS/Linux:

# Generic (works for any version)
export KICAD_SYMBOL_DIR=/Applications/KiCad/KiCad.app/Contents/SharedSupport/symbols

# Version-specific (if you have KiCAD 8)
export KICAD8_SYMBOL_DIR=/Applications/KiCad806/KiCad.app/Contents/SharedSupport/symbols/

# Add to ~/.bashrc or ~/.zshrc to make permanent
echo 'export KICAD8_SYMBOL_DIR=/Applications/KiCad806/KiCad.app/Contents/SharedSupport/symbols/' >> ~/.zshrc

Windows PowerShell:

$env:KICAD8_SYMBOL_DIR="C:\Program Files\KiCad\8.0\share\kicad\symbols"

# Make permanent:
[System.Environment]::SetEnvironmentVariable('KICAD8_SYMBOL_DIR', 'C:\Program Files\KiCad\8.0\share\kicad\symbols', 'User')

Step 3: Verify Configuration

Create a test script:

#!/usr/bin/env python3
import kicad_sch_api as ksa

# Test library discovery
cache = ksa.SymbolLibraryCache(enable_persistence=False)
lib_count = cache.discover_libraries()

print(f"Discovered {lib_count} libraries")

# Test loading a symbol
symbol = cache.get_symbol("Device:R")
if symbol:
    print("✓ Successfully loaded Device:R")
else:
    print("✗ Failed to load symbol")