skill

KiCad Service

Unreviewed

by Kyle Bergstedt

Use when the user asks about the KiCad service, KiCad CLI, DRC validation, ERC, Gerber export, symbol/footprint SVG rendering, STEP/GLB 3D model export, or any headless KiCad operation.

Overview Files Versions Dependencies Discussions Activity
skill / kicad-service
!

Not installable via adompkg

This skill has no published release. adompkg install kyle/kicad-service will not work until a maintainer publishes a tarball with install.sh and uninstall.sh.

See the publishing docs for the package.json schema and tarball layout required to ship this skill.

KiCad Service

A shared KiCad CLI HTTP service running on a dedicated Adom container. Provides headless KiCad operations without needing KiCad installed locally.

This is NOT the same as adom-desktop KiCad control. Two different things:

KiCad Service (this skill) adom-desktop KiCad
Where KiCad runs Dedicated server container User's Windows/Mac desktop
GUI None — headless CLI only Full KiCad GUI (schematic editor, PCB layout, 3D viewer)
What it does DRC, Gerber export, SVG rendering, STEP/GLB export, symbol/footprint search Open/close editors, install symbols/footprints, screenshot windows, handle dialogs
Install needed None — already running Yes — user installs Adom Desktop app
Best for Automated validation, rendering, batch export Interactive editing, visual inspection, demo recordings

When to use which

  • "Run DRC on my board" → KiCad Service (this skill)
  • "Open my schematic in KiCad" → adom-desktop (needs desktop install)
  • "Export gerbers from a .kicad_pcb file" → KiCad Service
  • "Show me the KiCad Symbol Editor" → adom-desktop
  • "Render my footprint as SVG" → KiCad Service
  • "Install this symbol into KiCad's library" → adom-desktop

Service URL

https://coder.john-service-kicad-cli-5948815f6104358b.containers.adom.inc/proxy/8780

This is a shared service available to all Adom containers. Use $KICAD_API if set, otherwise use the URL above.

# Health check
curl -s "https://coder.john-service-kicad-cli-5948815f6104358b.containers.adom.inc/proxy/8780/health"
# → {"ok":true,"kicad_version":"9.0.7","uptime_seconds":...}

API Client

JavaScript client with all functions:

import { checkHealth, symSearch, pcbDrc, pcbExportGerbers, ... } from '/home/adom/project/gallia/viewer/kicad-api-client.js';

Available Operations

Health Check

const health = await checkHealth();
// → { ok: true, kicadVersion: "9.0.1", uptimeSeconds: 12345, cacheSizeMb: 42 }

Symbol Operations

// Search for symbols
const results = await symSearch("STM32F103", 20);

// Get symbol details
const sym = await symGet("Device", "R");

// Export symbol as SVG
const svg = await symExportSvg("/path/to/file.kicad_sym", "SYMBOL_NAME");

// Export by library+name (cached)
const svg = await symExportSvgByName("Device", "R");

Footprint Operations

// List footprints
const fps = await fpList({ library: "Package_SO" });

// Export footprint as SVG
const svg = await fpExportSvg("/path/to/file.kicad_mod", "SOT-23");
const svg = await fpExportSvgByName("Package_SO", "SOT-23");

// Export as GLB (3D model)
const glb = await fpExportGlbByName("Package_SO", "SOT-23", "/tmp/sot23.glb");

// Export as STEP
const step = await fpExportStepByName("Package_SO", "SOT-23", "/tmp/sot23.step");

// Download footprint file
await fpDownload("Package_SO/SOT-23.kicad_mod", "/tmp/sot23.kicad_mod");

PCB / Board Operations

// Run Design Rule Check
const drc = await pcbDrc("/path/to/board.kicad_pcb");
// → { violations: [...], errorCount: 2, warningCount: 5 }

// Export Gerbers
const gerbers = await pcbExportGerbers("/path/to/board.kicad_pcb", "/tmp/gerbers/");

// Export board as GLB (3D model)
const glb = await boardExportGlb("/path/to/board.kicad_pcb", "/tmp/board.glb");

// Export footprint from PCB as STEP
const step = await pcbExportStep("/path/to/board.kicad_pcb", "U1", "/tmp/u1.step");

3D Model Operations

// List available 3D models
const models = await models3dList({ library: "Package_SO" });

// Download a 3D model
await models3dDownload("Package_SO/SOT-23.step", "/tmp/sot23.step");

Error Handling

The health check distinguishes three failure modes:

  1. Service healthy — KiCad CLI available, ready for operations
  2. Node process down — Container running but Node server crashed. The service auto-restarts, retry in 30s.
  3. Container unreachable — ECONNREFUSED/ETIMEDOUT. Container may be stopped or not provisioned.
const health = await checkHealth();
if (!health.ok) {
  console.error(health.status);     // 'node_down' | 'container_unreachable' | 'unknown_error'
  console.error(health.suggestion); // Human-readable fix suggestion
}

Which skills use the KiCad Service

  • board-creator — DRC validation on generated PCB boards
  • symbol-creator — SVG rendering of created symbols
  • footprint-creator — SVG rendering, STEP/GLB export of footprints
  • 3d-component-creator — GLB export for 3D viewer
  • gerber-viewer — Gerber file generation
  • instapcb — DRC before manufacturing submission
  • library-creator — Symbol/footprint validation

NOT the same as adom-desktop

If the user wants to:

  • See the KiCad GUI → they need adom-desktop (install the desktop app)
  • Open a schematic in the editor → adom-desktop
  • Install a symbol into their local KiCad library → adom-desktop
  • Control KiCad windows, handle dialogs → adom-desktop

This service is for headless, API-driven operations only.