init

The kilm init command prepares the current working directory to be managed by KiLM as a library collection, primarily intended for symbol, footprint, and template libraries (often managed via Git, hence the internal type github).

It performs several actions:

1. Creates standard subdirectories (symbols/, footprints/, templates/) if they don’t exist.
2. Creates a template library_descriptions.yaml file if it doesn’t exist, used for richer descriptions in KiCad.
3. Creates or updates a metadata file named kilm.yaml within the current directory. This stores the library’s name, description, associated environment variable, and detected capabilities (symbols, footprints, templates).
4. Adds an entry for this library (with its path and type github) to the main KiLM configuration file (~/.config/kicad-lib-manager/config.yaml).
5. Optionally sets this library as the current_library in the main configuration.

Usage

Run this command from within the directory you want to initialize:

cd /path/to/your-library
kilm init [OPTIONS]

Options

Option	Description	Default	Example
--name TEXT	Custom name for the library collection	Auto-generated from directory name	--name my-custom-library
--description TEXT	Description for the library metadata	None	--description "My collection of custom components"
--env-var TEXT	Custom KiCad environment variable name	Auto-generated (e.g., KICAD_LIB_MY_LIBRARY)	--env-var MY_LIB_PATH
--no-env-var	Don’t assign an environment variable to this library	False	--no-env-var
--set-current/--no-set-current	Set this as the current active library	True	--no-set-current
--force	Overwrite existing metadata file if present	False	--force
--help	Show help message and exit	-	--help

Behavior

The command performs the following actions:

1. Creates Directory Structure: Creates standard subdirectories (symbols/, footprints/, templates/) if they don’t exist

2. Creates Template Files: Creates a template library_descriptions.yaml file for richer KiCad descriptions

3. Creates/Updates Metadata: Creates or modifies kilm.yaml with library information:

   • Library name, description, and environment variable
   • Detected capabilities (symbols, footprints, templates)
   • Last updated timestamp

4. Updates Global Configuration: Adds library entry (type github) to main config.yaml

5. Sets Default Library: Optionally sets this library as the current active library

Examples

Basic Usage

Initialize current directory as KiCad library:

# Navigate to your library directory
cd ~/my-kicad-libraries

# Initialize with default settings
kilm init

Initialize with custom name and description:

cd ~/company-components
kilm init --name company-symbols --description "Company-wide KiCad components"

Advanced Configuration

Initialize with custom environment variable:

cd ~/project-libraries
kilm init --name project-libs   --description "Project-specific components"   --env-var PROJECT_COMPONENTS   --no-set-current

Force re-initialization:

cd ~/existing-library
kilm init --force --name updated-library

Workflow Examples

Complete library setup workflow:

# 1. Create and initialize library
mkdir ~/my-symbols && cd ~/my-symbols
kilm init --name my-symbols --description "My custom symbols"

# 2. Add your symbol files to symbols/ directory
# Copy your .kicad_sym files to symbols/

# 3. Configure KiCad to use the library
kilm setup

# 4. Verify setup
kilm status

Error Handling

Common Issues

• Permission denied: Command will fail if unable to create directories or files
• Existing library: Use --force to overwrite existing metadata
• Invalid directory: Command must be run in a writable directory
• Configuration error: Command will fail if unable to update global config

Error Examples

# No write permissions
cd /readonly/directory
kilm init
# Error: Permission denied when creating directories

# Directory doesn't exist
cd /nonexistent/path
kilm init
# Error: Directory does not exist

Integration with Other Commands

setup Configure KiCad to use the initialized library

status Check the status of initialized libraries

update Update Git-based libraries after initialization

config Manage library configuration and settings

Typical Workflow

After running kilm init, you typically need to:

1. Add your library files: Place .kicad_sym files in symbols/, .pretty directories in footprints/
2. Run setup: Execute kilm setup to configure KiCad to use the library
3. Verify: Use kilm status to check that everything is configured correctly

Generated Files

The command creates the following files and directories:

Directory Structure

• Directoryyour-library

  • Directorysymbols/ # Directory for .kicad_sym files

    • …
  • Directoryfootprints/ # Directory for .pretty directories

    • …
  • Directorytemplates/ # Directory for project templates

    • …
  • kilm.yaml # Library metadata (created/updated)
  • library_descriptions.yaml # KiCad descriptions (created if missing)

Metadata File

kilm.yaml

name: "my-library"
description: "My KiCad library"
env_var: "KICAD_LIB_MY_LIBRARY"
capabilities:
symbols: true
footprints: true
templates: false
version: "1.0.0"
updated_with: "kilm"

Notes

• Working Directory: Command must be run from within the directory you want to initialize
• Environment Variables: Use kilm setup to activate configured environment variables in KiCad
• Cross-platform: Works on Windows, macOS, and Linux with appropriate path handling
• Git Integration: Designed for Git-managed libraries but works with any directory structure
• Safe Updates: Preserves existing metadata unless --force is used