add-3d

The kilm add-3d command registers a directory containing 3D models (like .step or .wrl files) with KiLM. This is typically used for libraries stored outside the main symbol/footprint Git repository, such as in cloud-synced folders.

Usage

kilm add-3d [OPTIONS]

Options

Option	Description	Default	Example
--directory DIRECTORY	Path to the directory containing 3D models	Current working directory	--directory ~/kicad/3d-models
--name TEXT	Custom name for this 3D library entry	Auto-generated from directory name	--name standard-3d-lib
--description TEXT	Description for this 3D library	None	--description "My custom STEP models"
--env-var TEXT	Custom KiCad environment variable name	Auto-generated (e.g., KICAD_3D_STANDARD_3D_LIB)	--env-var KICAD_USER_3DMOD
--no-env-var	Don’t assign an environment variable to this library	False	--no-env-var
--force / --no-force	Overwrite existing metadata file if present	--no-force	--force
--help	Show help message and exit	-	--help

Behavior

The command performs the following main actions:

1. Creates/Updates Metadata: Creates or modifies .kilm_metadata in the target directory containing:

   • Library name, description, and associated environment variable
   • Count of detected model files

   Other fields already in the file are kept as they are, unless an option replaces them or --force starts the file afresh.

2. Updates Global Configuration: Adds library entry (type cloud) to main config.yaml

3. Verification: Scans directory for common 3D model file extensions (.step, .stp, .wrl, .wings)

4. Environment Variable Setup: Prepares environment variable for use with kilm setup

Examples

Basic Usage

Add a 3D library with automatic configuration:

# Add directory with default settings
kilm add-3d --directory ~/my-3d-parts --description "Custom 3D mechanical parts"

Add current directory as 3D library:

cd ~/kicad-3d-models
kilm add-3d --name my-3d-models --description "Project-specific 3D models"

Advanced Configuration

Add with custom environment variable:

kilm add-3d --directory /opt/kicad/packages3d \
    --name kicad-official-3d \
    --env-var KICAD_OFFICIAL_3D \
    --description "KiCad Official 3D Models"

Add without environment variable:

kilm add-3d --directory ~/local-3d-models \
    --name local-models \
    --no-env-var \
    --description "Local 3D models (no env var needed)"

Force overwrite existing metadata:

kilm add-3d --directory ~/existing-3d-lib \
    --force \
    --name updated-3d-lib \
    --description "Updated description"

Error Handling

Common Issues

• No 3D models found: Command will warn but allow continuation
• Directory not found: Command will fail with clear error message
• Permission denied: Command will fail if unable to write metadata file
• Existing metadata: Use --force to overwrite or command will update existing file

Error Examples

# Directory doesn't exist
kilm add-3d --directory /nonexistent/path
# Error: Directory '/nonexistent/path' does not exist

# No write permissions
kilm add-3d --directory /readonly/directory
# Error: Permission denied when creating metadata file

Integration with Other Commands

setupConfigure KiCad to use the registered 3D libraries

statusCheck current configuration status including 3D libraries

configManage library configuration and defaults

Workflow Integration

After adding 3D libraries, you typically need to run kilm setup to make them available in KiCad:

# Add 3D library
kilm add-3d --directory ~/my-3d-models --name my-models

# Configure KiCad to use it
kilm setup --all-libraries

# Verify configuration
kilm status

File Extensions Supported

The command automatically detects these 3D model file extensions:

• .step - STEP files
• .stp - STEP files (alternative extension)
• .wrl - VRML files
• .wings - Wings 3D files

Notes

• Environment Variables: Use kilm setup to activate the configured environment variables in KiCad
• Cross-platform: Works on Windows, macOS, and Linux with appropriate path handling
• Metadata Storage: Library information is stored in .kilm_metadata in the target directory
• KiCad Integration: Requires kilm setup to complete the integration with KiCad