Maykol Rey

Ing. Electrónico

04/05/2026

KiCad CLI: automatiza ERC, DRC, Gerbers, BOM y documentación para fabricar PCBs sin errores

Diseñar una PCB no termina cuando el esquemático “se ve bien” o cuando el layout ya está ruteado. Antes de enviar un diseño a fabricación, hay que validar reglas eléctricas, revisar reglas de diseño, exportar Gerbers, generar archivos de taladro, crear documentación, preparar BOM y, muchas veces, repetir todo ese proceso cada vez que se hace un pequeño cambio.

Ahí es donde KiCad CLI se vuelve una herramienta poderosa.

kicad-cli es la interfaz de línea de comandos de KiCad. Permite ejecutar acciones sobre esquemáticos, PCBs, símbolos y footprints de forma automatizada, sin abrir la interfaz gráfica de KiCad.¹ En otras palabras: lleva parte del flujo de diseño electrónico al mundo de los scripts, la integración continua y la fabricación reproducible.

Si trabajas con hardware profesional, documentación técnica, control de versiones o pipelines de validación, KiCad CLI puede convertirse en una pieza clave de tu flujo de trabajo.

¿Qué es KiCad CLI?

KiCad CLI es el ejecutable de línea de comandos disponible como kicad-cli. Su objetivo es permitir que tareas comunes de KiCad se puedan ejecutar desde terminal, scripts o sistemas CI/CD.¹

Con KiCad CLI puedes, por ejemplo:

Ejecutar el ERC del esquemático.
Ejecutar el DRC de la PCB.
Exportar Gerbers.
Exportar archivos de taladro.
Exportar archivos de posición de componentes.
Generar una BOM.
Exportar documentación en PDF.
Exportar modelos STEP.
Renderizar imágenes de la PCB.
Ejecutar jobsets predefinidos.

La documentación de KiCad 9 indica que kicad-cli tiene seis subcomandos principales: fp, jobset, pcb, sch, sym y version.² Esta estructura permite separar las acciones según el tipo de recurso: esquemático, PCB, footprints, símbolos o jobs.

¿Por qué usar KiCad CLI?

La ventaja principal no es “usar KiCad desde terminal” por moda. La ventaja real es reducir errores repetitivos y hacer el proceso de fabricación más confiable.

Cuando un proyecto crece, aparecen preguntas como:

¿La última versión del esquemático pasó ERC?
¿El layout pasó DRC antes de generar Gerbers?
¿Los archivos de fabricación fueron exportados con los mismos parámetros?
¿La documentación PDF corresponde exactamente a la versión fabricada?
¿Alguien modificó la PCB y olvidó regenerar el paquete de fabricación?

Con KiCad CLI puedes convertir esas tareas en comandos repetibles.

En vez de depender de que una persona recuerde hacer clic en varios menús, puedes tener un script como este:

kicad-cli sch erc hardware/proyecto.kicad_sch --exit-code-violations
kicad-cli pcb drc hardware/proyecto.kicad_pcb --exit-code-violations
kicad-cli pcb export gerbers hardware/proyecto.kicad_pcb -o output/gerbers
kicad-cli pcb export drill hardware/proyecto.kicad_pcb -o output/drill

El resultado es un flujo más ordenado, documentado y menos dependiente de pasos manuales.

Casos de uso de KiCad CLI

1. Validar el esquemático automáticamente

El comando sch erc ejecuta el Electrical Rules Check sobre un archivo esquemático y genera un reporte.³

kicad-cli sch erc hardware/proyecto.kicad_sch \
  --output reports/erc.rpt \
  --exit-code-violations

La opción --exit-code-violations permite que el comando devuelva un código de salida diferente si encuentra violaciones. En KiCad 9, el código es 0 si no hay violaciones y 5 si se encuentran violaciones.⁴

Esto es especialmente útil en CI/CD, porque permite detener un pipeline cuando el esquemático tiene errores eléctricos.

2. Validar la PCB con DRC

El comando pcb drc ejecuta el Design Rules Check sobre el archivo de PCB y genera un reporte.⁵

kicad-cli pcb drc hardware/proyecto.kicad_pcb \
  --output reports/drc.rpt \
  --exit-code-violations

Este comando puede ayudarte a detectar problemas como:

Pistas demasiado cercanas.
Vías fuera de regla.
Pads mal conectados.
Problemas de clearance.
Errores relacionados con reglas de fabricación.

Si trabajas con restricciones industriales, alta corriente, señales rápidas o diseños para ambientes exigentes, automatizar el DRC es una forma simple de reducir riesgos antes de fabricar.

3. Exportar Gerbers para fabricación

El comando recomendado para fabricación es pcb export gerbers, porque genera un archivo Gerber por cada capa de PCB.⁶

mkdir -p output/gerbers

kicad-cli pcb export gerbers hardware/proyecto.kicad_pcb \
  -o output/gerbers

KiCad distingue entre gerber y gerbers: gerber exporta varias capas en un solo archivo, mientras que gerbers genera múltiples archivos, uno por capa. La propia documentación indica que gerbers suele ser el comando correcto cuando el objetivo es fabricar una PCB.⁷

4. Exportar archivos de taladro

Los archivos de taladro son necesarios para fabricar agujeros, vías y pads through-hole. KiCad CLI permite exportarlos con pcb export drill.⁸

mkdir -p output/drill

kicad-cli pcb export drill hardware/proyecto.kicad_pcb \
  -o output/drill

También puedes generar mapas de taladro o ajustar el formato según las necesidades del fabricante.

5. Exportar archivo de posición para ensamblaje

Si vas a mandar ensamblar la PCB, necesitarás un archivo de posición de componentes. KiCad CLI usa el comando pcb export pos para generar este archivo.⁹

kicad-cli pcb export pos hardware/proyecto.kicad_pcb \
  --output output/assembly/positions.csv \
  --format csv \
  --units mm \
  --side both

Este archivo es útil para procesos de pick and place, revisión de ensamblaje o documentación interna.

6. Exportar la BOM

La BOM puede generarse desde el esquemático con sch export bom.¹⁰

kicad-cli sch export bom hardware/proyecto.kicad_sch \
  --output output/bom/bom.csv \
  --format-preset CSV

También puedes controlar campos, etiquetas, agrupamiento, ordenamiento y exclusión de componentes marcados como DNP, según las opciones del comando.¹⁰

7. Exportar esquemático en PDF

Para documentación técnica, revisión interna o liberación de una versión, puedes exportar el esquemático a PDF con sch export pdf.¹¹

kicad-cli sch export pdf hardware/proyecto.kicad_sch \
  --output output/docs/schematic.pdf

Esto permite que la documentación se genere junto con los archivos de fabricación.

8. Exportar la PCB en PDF

También puedes exportar capas de la PCB en PDF con pcb export pdf.¹²

kicad-cli pcb export pdf hardware/proyecto.kicad_pcb \
  --output output/docs/pcb.pdf \
  --layers F.Cu,B.Cu,F.SilkS,B.SilkS,Edge.Cuts

Este archivo puede servir para revisión de manufactura, documentación de producto o inspección rápida.

9. Exportar modelo STEP

Para diseño mecánico, integración con carcasas o revisión de ensamble, KiCad CLI permite exportar la PCB a STEP.¹³

kicad-cli pcb export step hardware/proyecto.kicad_pcb \
  --output output/3d/proyecto.step

Este flujo es muy útil si trabajas con FreeCAD, SolidWorks, Fusion 360 u otra herramienta MCAD.

10. Renderizar una imagen de la PCB

KiCad CLI también puede generar un render raytraced de la PCB y guardarlo como PNG o JPEG.¹⁴

kicad-cli pcb render hardware/proyecto.kicad_pcb \
  --output output/images/pcb-render.png \
  --width 1600 \
  --height 900 \
  --side top

Esto sirve para documentación, revisión visual, publicaciones, README de GitHub o entregables técnicos.

Workflow recomendado con KiCad CLI

Un buen workflow no consiste solo en exportar archivos. Consiste en definir una secuencia clara para liberar un diseño.

Workflow básico para una PCB

1. Diseñar esquemático
2. Ejecutar ERC
3. Diseñar PCB
4. Ejecutar DRC
5. Exportar Gerbers
6. Exportar drill
7. Exportar BOM
8. Exportar posiciones
9. Exportar documentación PDF
10. Empaquetar archivos de fabricación

Con KiCad CLI, este flujo puede convertirse en un script.

Caso práctico: script de liberación para fabricación

Supongamos que tienes esta estructura de proyecto:

mi-proyecto/
├── hardware/
│   ├── mi-proyecto.kicad_pro
│   ├── mi-proyecto.kicad_sch
│   └── mi-proyecto.kicad_pcb
├── scripts/
│   └── release-hardware.sh
└── output/

Puedes crear un script llamado scripts/release-hardware.sh:

#!/usr/bin/env bash
set -e

PROJECT_NAME="mi-proyecto"
SCH="hardware/${PROJECT_NAME}.kicad_sch"
PCB="hardware/${PROJECT_NAME}.kicad_pcb"

OUT="output"
REPORTS="${OUT}/reports"
GERBERS="${OUT}/fabrication/gerbers"
DRILL="${OUT}/fabrication/drill"
ASSEMBLY="${OUT}/assembly"
DOCS="${OUT}/docs"
MODEL="${OUT}/3d"
IMAGES="${OUT}/images"

echo "Limpiando salida anterior..."
rm -rf "$OUT"

echo "Creando carpetas..."
mkdir -p "$REPORTS" "$GERBERS" "$DRILL" "$ASSEMBLY" "$DOCS" "$MODEL" "$IMAGES"

echo "Ejecutando ERC..."
kicad-cli sch erc "$SCH" \
  --output "${REPORTS}/erc.rpt" \
  --exit-code-violations

echo "Ejecutando DRC..."
kicad-cli pcb drc "$PCB" \
  --output "${REPORTS}/drc.rpt" \
  --exit-code-violations

echo "Exportando Gerbers..."
kicad-cli pcb export gerbers "$PCB" \
  -o "$GERBERS"

echo "Exportando archivos de taladro..."
kicad-cli pcb export drill "$PCB" \
  -o "$DRILL"

echo "Exportando posiciones..."
kicad-cli pcb export pos "$PCB" \
  --output "${ASSEMBLY}/positions.csv" \
  --format csv \
  --units mm \
  --side both

echo "Exportando BOM..."
kicad-cli sch export bom "$SCH" \
  --output "${ASSEMBLY}/bom.csv" \
  --format-preset CSV

echo "Exportando esquemático en PDF..."
kicad-cli sch export pdf "$SCH" \
  --output "${DOCS}/schematic.pdf"

echo "Exportando PCB en PDF..."
kicad-cli pcb export pdf "$PCB" \
  --output "${DOCS}/pcb.pdf" \
  --layers F.Cu,B.Cu,F.SilkS,B.SilkS,Edge.Cuts

echo "Exportando STEP..."
kicad-cli pcb export step "$PCB" \
  --output "${MODEL}/${PROJECT_NAME}.step"

echo "Generando render..."
kicad-cli pcb render "$PCB" \
  --output "${IMAGES}/pcb-render.png" \
  --width 1600 \
  --height 900 \
  --side top

echo "Creando paquete ZIP..."
cd "$OUT"
zip -r "${PROJECT_NAME}-fabrication-package.zip" fabrication assembly docs reports 3d images

echo "Liberación completada correctamente."

Luego das permisos de ejecución:

chmod +x scripts/release-hardware.sh

Y lo ejecutas:

./scripts/release-hardware.sh

Este caso práctico tiene una lógica simple: si ERC o DRC fallan, el script se detiene antes de generar los archivos finales. Esto ocurre gracias a set -e y --exit-code-violations, que permite que las violaciones de ERC/DRC afecten el código de salida del comando.⁴

Workflow con GitLab CI

KiCad CLI también encaja muy bien en un pipeline de integración continua.

Un ejemplo básico para GitLab CI sería:

stages:
  - validate
  - build

variables:
  PROJECT_NAME: "mi-proyecto"
  SCH: "hardware/mi-proyecto.kicad_sch"
  PCB: "hardware/mi-proyecto.kicad_pcb"

validate_hardware:
  stage: validate
  image: kicad/kicad:9.0
  script:
    - mkdir -p output/reports
    - kicad-cli sch erc "$SCH" --output output/reports/erc.rpt --exit-code-violations
    - kicad-cli pcb drc "$PCB" --output output/reports/drc.rpt --exit-code-violations
  artifacts:
    when: always
    paths:
      - output/reports/

build_fabrication_package:
  stage: build
  image: kicad/kicad:9.0
  needs:
    - validate_hardware
  script:
    - mkdir -p output/gerbers output/drill output/assembly output/docs
    - kicad-cli pcb export gerbers "$PCB" -o output/gerbers
    - kicad-cli pcb export drill "$PCB" -o output/drill
    - kicad-cli pcb export pos "$PCB" --output output/assembly/positions.csv --format csv --units mm --side both
    - kicad-cli sch export bom "$SCH" --output output/assembly/bom.csv --format-preset CSV
    - kicad-cli sch export pdf "$SCH" --output output/docs/schematic.pdf
    - zip -r fabrication-package.zip output
  artifacts:
    paths:
      - fabrication-package.zip

Este pipeline hace dos cosas importantes:

Primero valida el diseño.
Solo si pasa la validación, genera el paquete de fabricación.

Este tipo de flujo ayuda a tratar el hardware con una lógica parecida al software: cambios versionados, validaciones automáticas y entregables reproducibles.

Workflow con Jobsets

KiCad también incluye el subcomando jobset. Según la documentación, jobset run permite ejecutar un jobset predefinido, usando un archivo .kicad_jobset y un proyecto como entrada.¹⁵

Ejemplo:

kicad-cli jobset run hardware/mi-proyecto.kicad_pro \
  --file hardware/release.kicad_jobset \
  --stop-on-error

La opción --stop-on-error hace que la ejecución se detenga cuando falle un job dentro de la secuencia.¹⁵

Este enfoque es interesante cuando quieres definir tareas de exportación desde KiCad y luego ejecutarlas desde terminal o CI.

Buenas prácticas para usar KiCad CLI

1. Versiona tu proyecto completo

Guarda en Git los archivos principales de KiCad:

.kicad_pro
.kicad_sch
.kicad_pcb
.kicad_sym
.pretty/
.kicad_jobset

También conviene versionar scripts de exportación y documentación del flujo.

2. Separa carpetas de salida

No mezcles archivos fuente con archivos generados. Usa carpetas como:

output/
dist/
release/
fabrication/

Esto facilita limpiar, regenerar y empaquetar entregables.

3. No exportes Gerbers manualmente si puedes automatizarlo

Un error común es exportar Gerbers manualmente, modificar la PCB y olvidar regenerar los archivos. Con un script, cada paquete de fabricación puede generarse desde cero.

4. Usa `--help`

KiCad recomienda usar --help o -h para consultar información de cada subcomando.²

Ejemplos:

kicad-cli --help
kicad-cli pcb --help
kicad-cli pcb export gerbers --help
kicad-cli sch erc --help

5. Fija la versión de KiCad en CI

Los comandos y opciones pueden variar entre versiones. La documentación de KiCad 9.0 indica que la funcionalidad y apariencia pueden ser diferentes en otras versiones.¹⁶ Por eso, si usas CI/CD, fija una imagen o versión concreta, por ejemplo:

image: kicad/kicad:9.0

Errores comunes al usar KiCad CLI

Error 1: usar `gerber` en vez de `gerbers`

Para fabricación, normalmente necesitas un archivo por capa. En KiCad 9, la documentación indica que gerbers suele ser el comando correcto para fabricar, mientras que gerber exporta varias capas en un solo archivo y además está marcado como obsoleto en KiCad 9.⁷

Usa:

kicad-cli pcb export gerbers proyecto.kicad_pcb -o output/gerbers

Error 2: no usar `--exit-code-violations`

Sin esta opción, puedes generar reportes pero no necesariamente detener un pipeline cuando hay violaciones. Para CI/CD, conviene usar:

--exit-code-violations

Error 3: exportar archivos sin limpiar la carpeta anterior

Si no limpias la carpeta de salida, puedes mezclar archivos antiguos con archivos nuevos. Lo más seguro es generar cada release desde una carpeta vacía.

Error 4: asumir que todos los fabricantes piden lo mismo

Aunque KiCad CLI genera los archivos, cada fabricante puede pedir capas, formatos, unidades o nombres específicos. El script debe ajustarse a los requisitos del proveedor de fabricación.

Preguntas frecuentes sobre KiCad CLI

¿KiCad CLI reemplaza a la interfaz gráfica?

No. KiCad CLI complementa la interfaz gráfica. Diseñas y revisas visualmente en KiCad, pero automatizas validaciones, exportaciones y generación de entregables desde terminal.

¿Puedo generar Gerbers desde KiCad CLI?

Sí. El comando pcb export gerbers exporta la PCB a archivos Gerber, un archivo por capa.⁶

kicad-cli pcb export gerbers proyecto.kicad_pcb -o output/gerbers

¿Puedo ejecutar DRC desde terminal?

Sí. El comando pcb drc ejecuta el DRC sobre un archivo .kicad_pcb y genera un reporte.⁵

kicad-cli pcb drc proyecto.kicad_pcb --output reports/drc.rpt

¿Puedo ejecutar ERC desde terminal?

Sí. El comando sch erc ejecuta el ERC sobre un archivo .kicad_sch y genera un reporte.³

kicad-cli sch erc proyecto.kicad_sch --output reports/erc.rpt

¿KiCad CLI sirve para CI/CD?

Sí. KiCad CLI es especialmente útil para CI/CD porque permite validar y exportar proyectos de hardware de forma automática. La opción --exit-code-violations es clave porque permite que ERC/DRC devuelvan un código de salida según existan o no violaciones.⁴

¿Puedo exportar una BOM con KiCad CLI?

Sí. El comando sch export bom exporta una BOM desde el esquemático y permite controlar formato, campos, agrupamiento y filtros.¹⁰

¿Puedo exportar un modelo 3D STEP?

Sí. El comando pcb export step exporta el diseño de PCB a un archivo STEP.¹³

¿Puedo usar KiCad CLI en macOS?

Sí. En macOS, la documentación indica que el ejecutable se encuentra en:

/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli

¿Cómo sé qué opciones soporta mi versión?

Usa --help:

kicad-cli pcb export gerbers --help

La documentación recomienda --help o -h para ver información de cada subcomando.²

¿Qué versión debo usar?

Depende de tu proyecto. Si trabajas con un equipo o con CI/CD, lo recomendable es fijar una versión y no cambiarla sin revisar los comandos. KiCad advierte que la funcionalidad puede variar entre versiones.¹⁶

Conclusión

KiCad CLI es una herramienta estratégica para cualquier flujo de diseño electrónico que busque orden, repetibilidad y control.

No se trata solo de exportar Gerbers desde terminal. Se trata de construir un proceso donde cada versión de hardware pueda validarse, documentarse y liberarse de forma confiable.

Un buen flujo con KiCad CLI permite pasar de esto:

Abrir KiCad → revisar manualmente → exportar manualmente → comprimir archivos → esperar que todo esté correcto

A esto:

Ejecutar script → validar ERC/DRC → exportar fabricación → generar documentación → crear paquete final

Para proyectos personales puede parecer un extra. Para hardware profesional, documentación técnica, productos industriales o equipos de desarrollo, puede marcar una gran diferencia.