@typecad/kicad-symbols

Intelligent fuzzy search for KiCad schematic symbols with CLI interface. This TypeScript-based npm package provides smart symbol search capabilities by processing local KiCad symbol files and offering natural language search with intelligent parameter matching.

Features

• 🔍 Intelligent Fuzzy Search: Find KiCad symbols using natural language descriptions
• 📁 Local File Processing: Processes KiCad symbol files directly from your installation
• ⚡ Fast CLI Interface: Quick command-line searches with formatted output
• 🎯 Smart Symbol Matching: Recognizes library names, symbol names, and descriptions
• 📊 Scored Results: Get ranked results with match explanations
• 🔄 Automatic Caching: Caches processed symbols for fast subsequent searches
• 🎨 Multiple Output Formats: Detailed, compact, table, or JSON display options
• 🔧 Programmatic Integration: JSON output for scripting and automation
• 💬 Interactive Mode: Prompt for search queries when none provided via command line

Installation

Global Installation (Recommended)

npm install -g @typecad/kicad-symbols

After global installation, you can use the kicad-symbols command from anywhere:

kicad-symbols "op amp"

Quick Start

Basic Search

# Search for operational amplifier symbols
kicad-symbols "op amp"

# Search for microcontroller symbols
kicad-symbols "microcontroller"

# Search for connector symbols
kicad-symbols "connector"

Interactive Mode

If you run the program without any search query, it will prompt you to enter one interactively:

# Start the program without arguments
kicad-symbols

# The program will display:
# kicad-symbols - KiCad Symbols Search Tool
# No search query provided. Please enter a search term:
# Examples: "capacitor", "LM358", "4xxx:14528", "op amp"
# Press Ctrl+C to exit
# 
# Search query: 

Advanced Usage

# Use table format for compact display
kicad-symbols "LM358" --format table

# Sort by library and show 1 result
kicad-symbols "transistor" --sort id --limit 1

# Compact format for quick overview
kicad-symbols "LED" --format compact

# JSON format for programmatic use
kicad-symbols "capacitor" --format json

Usage

Command Line Interface

kicad-symbols [options] [<search query>]

Options:
  -h, --help                Display help message
  -v, --version             Display version information
  -f, --format <format>     Output format: detailed, compact, table, or json (default: detailed)
  -s, --sort <field>        Sort by: score, id, manufacturer, or package (default: score)
  -l, --limit <number>      Limit number of results (default: 5)

Note: If no search query is provided, the program will prompt you to enter one interactively.

Search Query Examples

The tool understands natural language descriptions and can find KiCad symbols by name, library, or description:

Analog Components

kicad-symbols "op amp"                       # Operational amplifier symbols
kicad-symbols "LM358"                        # Specific op amp part
kicad-symbols "comparator"                   # Comparator symbols

Digital Logic

kicad-symbols "74HC00"                       # Logic gate symbols
kicad-symbols "flip flop"                    # Flip-flop symbols
kicad-symbols "counter"                      # Counter IC symbols

Microcontrollers

kicad-symbols "STM32"                        # STM32 microcontroller symbols
kicad-symbols "Arduino"                      # Arduino-related symbols
kicad-symbols "PIC"                          # PIC microcontroller symbols

Power Management

kicad-symbols "voltage regulator"            # Voltage regulator symbols
kicad-symbols "LDO"                          # Low dropout regulator symbols
kicad-symbols "switching regulator"          # Switching regulator symbols

Connectors and Interface

kicad-symbols "USB"                          # USB connector symbols
kicad-symbols "header"                       # Pin header symbols
kicad-symbols "terminal block"               # Terminal block symbols

Output Formats

Detailed Format (Default)

Shows complete symbol information with match explanations:

Found 3 matching symbols:

1. Amplifier_Operational:LM358 - Dual Low-Power Operational Amplifier
   Part Number: LM358
   Match Score: 95.0
   Match Details: Exact symbol match (100 pts), Library match (80 pts), Description match (70 pts)

Compact Format

One-line summary per symbol:

kicad-symbols "op amp" --format compact

1. Amplifier_Operational:LM358 - Dual Low-Power Operational Amplifier... - 95.0
2. Amplifier_Operational:LM324 - Quad Low-Power Operational Amplifier... - 87.5

Table Format

Structured table view:

kicad-symbols "transistor" --format table

#   Symbol                    Score  Description
--- ------------------------- ------ -----------
1   Transistor_BJT:BC547      92.0   NPN Bipolar Junction Transistor
2   Transistor_FET:2N7000     89.5   N-Channel Enhancement Mode MOSFET

JSON Format

Machine-readable JSON output for programmatic integration:

kicad-symbols "op amp" --format json

[
  {
    "symbol": "Amplifier_Operational:LM358",
    "description": "Dual Low-Power Operational Amplifier",
    "score": 95.0,
    "matchSummary": "Exact symbol match (100 pts), Library match (80 pts)"
  },
  {
    "symbol": "Amplifier_Operational:LM324",
    "description": "Quad Low-Power Operational Amplifier",
    "score": 87.5,
    "matchSummary": "Symbol match (90 pts), Library match (80 pts)"
  }
]

JSON Format Features:

• Clean Output: No formatting, colors, or progress indicators
• Machine-Readable: Valid JSON for easy parsing by scripts and applications
• Complete Data: All component information included in structured format
• Empty Results: Returns empty array [] when no components found
• Error Handling: Errors output as JSON objects with error information

JSON Error Response Format:

{
  "error": true,
  "message": "No search query provided",
  "code": "MISSING_QUERY"
}

How It Works

Local File Processing

The tool processes KiCad symbol files from your local installation:

1. Symbol Discovery: Automatically locates KiCad symbol libraries on your system
2. File Processing: Parses .kicad_sym files to extract symbol information
3. Caching: Stores processed symbols locally for fast subsequent searches
4. Auto-Update: Re-processes files when symbol libraries are updated

Intelligent Symbol Matching

The search engine recognizes and matches:

• Symbol Names: Exact and partial matches for symbol names
• Library Names: Matches against KiCad library categories
• Descriptions: Searches within symbol descriptions and functionality
• Part Numbers: Recognizes specific IC part numbers and families
• Component Types: Matches component categories and types
• Keywords: Searches for relevant technical terms and descriptions

Fuzzy Scoring Algorithm

Symbols are scored based on multiple factors:

• Exact Symbol Matches: 100 points for exact symbol name
• Library Matches: 80 points for matching library category
• Description Matches: 70 points for description relevance
• Partial Matches: 50-90 points for partial symbol/library matches
• Keyword Matches: 20-50 points for keyword relevance
• Category: 30 points for matching symbol category

Interactive Mode Behavior

When no search query is provided via command line arguments, the program enters interactive mode:

• User-Friendly Prompt: Displays a clear, colored prompt with helpful examples
• Graceful Exit: If you press Enter without typing anything, the program exits cleanly
• Cancel Support: Press Ctrl+C to exit the program at any time
• Same Functionality: All search features work exactly the same as command-line mode
• JSON Compatibility: Interactive mode respects JSON format settings for programmatic use

JSON Mode Behavior

When using the JSON format (--format json), the tool operates in a special mode optimized for programmatic use:

• Clean Output: No progress indicators, status messages, or colored text
• Pure JSON: Only valid JSON is output to stdout
• Error Handling: Errors are formatted as JSON objects with error information
• Exit Codes: Proper exit codes are maintained for error detection
• Performance: Slightly faster execution due to reduced formatting overhead

Programmatic Usage

You can also use the package programmatically in your Node.js applications:

import {
  Application,
  ComponentSearchEngine,
  DataManager,
  ElectricalParameterParser,
  EnhancedScoringSystem,
  runApplication,
} from "@typecad/kicad-symbols";

// Use the convenience function
await runApplication(process.argv, {
  cacheExpirationHours: 12,
});

// Or create your own application instance
const app = new Application(
  "kicad-symbols-cache.json", // cache file (ignored when using shared cache)
  "./cache", // cache directory (ignored when using shared cache)
  24, // cache expiration hours
  "my-kicad-search", // program name
  true // use shared temp directory for cache (default: true)
);

await app.run(process.argv);

Configuration

Environment Variables

• KICAD_CACHE_DIR: Directory to store cached files (default: current directory)
• KICAD_CACHE_HOURS: Cache check interval in hours (default: 24)

Cache Management

The tool stores cache files in a shared temporary directory to improve performance and allow multiple instances to share the same cache:

• kicad-symbols-cache.json: Processed symbol database cache
• .kicad-cache-timestamp: Cache metadata file
• .kicad-last-updated-date: Remote data update tracking

Cache files are stored in: {system-temp-directory}/kicad-symbols-cache/

To force a database refresh, you can either:

1. Wait for the cache to expire (24 hours by default)
2. Delete the cache directory manually
3. Use the application with a shorter cache expiration time

Troubleshooting

Common Issues

No Results Found

No symbols found matching your search criteria.
Suggestions:
- Try using more general terms (e.g., "amplifier" instead of "operational amplifier")
- Check your spelling and try alternative terms
- Remove specific parameters that might be too restrictive
- Try searching for symbol families instead of specific part numbers

Solutions:

• Use broader search terms
• Check spelling of symbol names and types
• Try alternative symbol categories or libraries
• Search for component families instead of specific part numbers

KiCad Not Found

Error: No local KiCad symbols found. Please ensure KiCad symbols are installed.

Solutions:

• Install KiCad on your system
• Ensure KiCad symbol libraries are installed
• Check that KiCad is properly configured
• Verify symbol library paths are accessible

Permission Errors

Error: Permission denied writing cache files

Solutions:

• Run from a directory where you have write permissions
• Check file system permissions
• Try running with elevated privileges (if appropriate)

Getting Help

• Use kicad-symbols --help for command-line help
• Run kicad-symbols without arguments to enter interactive mode for exploratory searches

Related Projects

• typeCAD - use TypeScript to create PCBs in KiCAD
• KiCad - Open source electronics design automation suite

Support

• Buy me a coffee
• 💡 Request features

Made by typeCAD