---
name: service-kicad
description: >
  Shared headless KiCad service for every Adom tool and user container.
  Run DRC, ERC, export to SVG/Gerber/STEP, convert Altium libraries,
  look up symbols, footprints, and 3D models — all via the
  `service-kicad` CLI. No local KiCad install needed.
  Trigger words: kicad service, service-kicad, kicad-cli remote,
  kicad DRC, kicad ERC, export gerbers, export step, board svg,
  schematic svg, altium to kicad, schlib, pcblib, kicad-packages3d,
  shared kicad library, headless kicad.
---

# service-kicad — shared headless KiCad

A shared KiCad 10 service running on a dedicated container. Every Adom
tool that needs KiCad operations (DRC, ERC, exports, library lookups)
shells to the `service-kicad` CLI instead of installing KiCad locally.

## Installation

```bash
adom-wiki pkg install adom/service-kicad
```

Installs the CLI, this skill, and bash completions. Verify with
`service-kicad health`.

## When to use

**Always use the `service-kicad` CLI** — never curl the service URL
directly. The CLI has the production endpoint baked in and insulates you
from container reprovisions that change the URL.

```bash
# Good — shell to the CLI
service-kicad pcb drc board.kicad_pcb
service-kicad pcb export step board.kicad_pcb --out board.step
service-kicad sym svg Connector_Generic Conn_01x04

# Bad — hardcoded URL, breaks on reprovision
curl -X POST --data-binary @board.kicad_pcb https://...adom.cloud/kicad/pcb/drc
```

**Don't** apt-install `kicad` on your container just to render one SVG.

**Board GLB is not exported here.** For a board 3D model, export STEP and
convert with `adom-step2glb` (molecule mode when the board has machine
pins). KiCad-native GLB bypasses the molecule pipeline — no anchoring,
gold pins, normalization, or footprint emit — and is gated behind
`--i-know-this-skips-the-pipeline`; anything it produces is
provenance-stamped (`asset.extras.adom.provenance = "kicad-native-glb"`).

## CLI commands

```bash
# Diagnostics
service-kicad health          # includes running git_sha
service-kicad version
service-kicad config          # effective URL + which override is active

# PCB
service-kicad pcb drc board.kicad_pcb [--format json] [--out report.json]
service-kicad pcb export svg board.kicad_pcb [--side top|bottom] [--layers F.Cu,F.Mask,Edge.Cuts] [--out board.svg]
service-kicad pcb export gerbers board.kicad_pcb [--out ./gerbers/]
service-kicad pcb export step board.kicad_pcb [--out board.step] [-F --include-pads ...]

# Schematic
service-kicad sch erc schematic.kicad_sch [--format json]
service-kicad sch export svg schematic.kicad_sch [--out sch.svg]
service-kicad sch export svg-project ./project-dir [--out ./sheets/]   # hierarchical: one SVG per sheet
service-kicad sch export pdf schematic.kicad_sch [--out sch.pdf]
service-kicad sch export bom schematic.kicad_sch [--out bom.csv]

# Altium → KiCad library conversion
service-kicad altium sym part.SchLib [--out part.kicad_sym]
service-kicad altium fp part.PcbLib [--out part.kicad_mod]

# Symbol / footprint SVG + raw fetch
service-kicad sym svg LIBRARY NAME [--out symbol.svg]
service-kicad sym fetch LIBRARY [--out lib.kicad_sym]
service-kicad fp svg LIBRARY NAME [--out footprint.svg]
service-kicad fp fetch LIBRARY NAME [--out fp.kicad_mod]

# 3D model download (official kicad-packages3d)
service-kicad model fetch PATH [--out model.step]
```

## Pointing at another instance (v9 pin, self-host)

```bash
export SERVICE_KICAD_URL=https://kicad-v9-7f1gq8j5ohbq.adom.cloud   # KiCad 9 fallback channel
export SERVICE_KICAD_URL=https://your-own-instance.example          # self-hosted
```

`service-kicad config` shows which URL is in effect and why.
(`KICAD_SERVICE_API` still works as a legacy alias.) Self-hosting is a
one-script deploy — see the README on the wiki page
(`adom-wiki repo clone adom/service-kicad`).

## Troubleshooting

| Exit | Meaning | Fix |
|---|---|---|
| **0** | ok | — |
| **1** | input invalid | Check path + that file parses under kicad-cli |
| **2** | service unreachable | `service-kicad health` to confirm; the container may be restarting |
| **3** | auth failed (401/403) | `adom-cli auth refresh` |
| **4** | service-side error | CLI prints stderr; usually input-specific |