Skip to content

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.

Terminal window
kilm add-3d [OPTIONS]
OptionDescriptionDefaultExample
--directory DIRECTORYPath to the directory containing 3D modelsCurrent working directory--directory ~/kicad/3d-models
--name TEXTCustom name for this 3D library entryAuto-generated from directory name--name standard-3d-lib
--description TEXTDescription for this 3D libraryNone--description "My custom STEP models"
--env-var TEXTCustom KiCad environment variable nameAuto-generated (e.g., KICAD_3D_STANDARD_3D_LIB)--env-var KICAD_USER_3DMOD
--no-env-varDon’t assign an environment variable to this libraryFalse--no-env-var
--forceOverwrite existing metadata file if presentFalse--force
--helpShow help message and exit---help

The command performs the following main actions:

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

    • Library name, description, and associated environment variable
    • Count of detected model files
    • Last updated timestamp
  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

Add a 3D library with automatic configuration:

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

Add current directory as 3D library:

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

Add with custom environment variable:

Terminal window
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:

Terminal window
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:

Terminal window
kilm add-3d --directory ~/existing-3d-lib \
--force \
--name updated-3d-lib \
--description "Updated description"
  • 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
Terminal window
# 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

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

Terminal window
# 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

The command automatically detects these 3D model file extensions:

  • .step - STEP files
  • .stp - STEP files (alternative extension)
  • .wrl - VRML files
  • .wings - Wings 3D files
  • 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_cloud_metadata in the target directory
  • KiCad Integration: Requires kilm setup to complete the integration with KiCad