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:

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.