kicad-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

KiCad CLI Reference

KiCad CLI 参考文档

Complete command reference for kicad-cli (KiCad 8.x)

适用于kicad-cli（KiCad 8.x版本）的完整命令参考

1. Command Structure

1. 命令结构

bash

kicad-cli <application> <command> [options] <input-file>

Applications:

```
sch
```
- Schematic operations
```
pcb
```
- PCB operations
```
fp
```
- Footprint operations
```
sym
```
- Symbol operations

bash

kicad-cli <application> <command> [options] <input-file>

可用应用模块：

```
sch
```
- 原理图操作
```
pcb
```
- PCB操作
```
fp
```
- 封装操作
```
sym
```
- 符号库操作

2. Schematic Commands

2. 原理图命令

Export Netlist

导出网表

bash

kicad-cli sch export netlist \
  --output project.net \
  project.kicad_sch

bash

kicad-cli sch export netlist \
  --output project.net \
  project.kicad_sch

Export BOM

导出物料清单（BOM）

bash

undefined

bash

undefined

Basic BOM

基础BOM

kicad-cli sch export bom
--output bom.csv
project.kicad_sch

With specific fields

自定义字段BOM

kicad-cli sch export bom
--output bom.csv
--fields "Reference,Value,Footprint,LCSC,MPN"
--group-by "Value,Footprint"
--sort-asc
project.kicad_sch

undefined

kicad-cli sch export bom
--output bom.csv
--fields "Reference,Value,Footprint,LCSC,MPN"
--group-by "Value,Footprint"
--sort-asc
project.kicad_sch

undefined

Export PDF

导出PDF

bash

kicad-cli sch export pdf \
  --output schematic.pdf \
  --black-and-white \
  project.kicad_sch

bash

kicad-cli sch export pdf \
  --output schematic.pdf \
  --black-and-white \
  project.kicad_sch

Export SVG

导出SVG

bash

kicad-cli sch export svg \
  --output ./svg/ \
  --black-and-white \
  project.kicad_sch

bash

kicad-cli sch export svg \
  --output ./svg/ \
  --black-and-white \
  project.kicad_sch

Run ERC (Electrical Rules Check)

运行电气规则检查（ERC）

bash

kicad-cli sch erc \
  --output erc-report.rpt \
  --severity-all \
  --exit-code-violations \
  project.kicad_sch

Options:

```
--severity-all
```
- Report all severities
```
--severity-error
```
- Only errors
```
--exit-code-violations
```
- Return non-zero on violations

bash

kicad-cli sch erc \
  --output erc-report.rpt \
  --severity-all \
  --exit-code-violations \
  project.kicad_sch

可选参数：

```
--severity-all
```
- 报告所有严重级别问题
```
--severity-error
```
- 仅报告错误
```
--exit-code-violations
```
- 检测到违规时返回非零退出码

3. PCB Commands

3. PCB命令

Run DRC (Design Rules Check)

运行设计规则检查（DRC）

bash

kicad-cli pcb drc \
  --output drc-report.rpt \
  --severity-all \
  --exit-code-violations \
  project.kicad_pcb

bash

kicad-cli pcb drc \
  --output drc-report.rpt \
  --severity-all \
  --exit-code-violations \
  project.kicad_pcb

Export Gerbers

导出Gerber文件

bash

kicad-cli pcb export gerbers \
  --output ./gerbers/ \
  --layers "F.Cu,B.Cu,F.SilkS,B.SilkS,F.Mask,B.Mask,Edge.Cuts" \
  --subtract-soldermask \
  project.kicad_pcb

Common layers:

```
F.Cu
```
,
```
B.Cu
```
- Copper layers
```
In1.Cu
```
,
```
In2.Cu
```
- Inner copper layers
```
F.SilkS
```
,
```
B.SilkS
```
- Silkscreen
```
F.Mask
```
,
```
B.Mask
```
- Solder mask
```
F.Paste
```
,
```
B.Paste
```
- Solder paste
```
Edge.Cuts
```
- Board outline
```
F.Fab
```
,
```
B.Fab
```
- Fabrication layers

bash

kicad-cli pcb export gerbers \
  --output ./gerbers/ \
  --layers "F.Cu,B.Cu,F.SilkS,B.SilkS,F.Mask,B.Mask,Edge.Cuts" \
  --subtract-soldermask \
  project.kicad_pcb

常用层：

```
F.Cu
```
,
```
B.Cu
```
- 铜箔层
```
In1.Cu
```
,
```
In2.Cu
```
- 内层铜箔
```
F.SilkS
```
,
```
B.SilkS
```
- 丝印层
```
F.Mask
```
,
```
B.Mask
```
- 阻焊层
```
F.Paste
```
,
```
B.Paste
```
- 钢网层
```
Edge.Cuts
```
- 板框层
```
F.Fab
```
,
```
B.Fab
```
- 制造层

Export Drill Files

导出钻孔文件

bash

kicad-cli pcb export drill \
  --output ./gerbers/ \
  --format excellon \
  --excellon-units mm \
  --generate-map \
  --map-format pdf \
  project.kicad_pcb

Options:

```
--format excellon
```
- Standard drill format
```
--excellon-units mm
```
or
```
in
```
```
--excellon-zeros-format decimal
```
```
--generate-map
```
- Create drill map
```
--map-format gerberx2|ps|pdf|svg|dxf
```

bash

kicad-cli pcb export drill \
  --output ./gerbers/ \
  --format excellon \
  --excellon-units mm \
  --generate-map \
  --map-format pdf \
  project.kicad_pcb

可选参数：

```
--format excellon
```
- 标准钻孔格式
```
--excellon-units mm
```
或
```
in
```
```
--excellon-zeros-format decimal
```
```
--generate-map
```
- 生成钻孔映射图
```
--map-format gerberx2|ps|pdf|svg|dxf
```

Export Position/Pick-and-Place

导出元件位置文件（贴片机用）

bash

kicad-cli pcb export pos \
  --output positions.csv \
  --format csv \
  --units mm \
  --side front \
  --exclude-dnp \
  project.kicad_pcb

Options:

```
--format csv|ascii
```
```
--units mm|in
```
```
--side front|back|both
```
```
--exclude-dnp
```
- Exclude Do Not Populate

bash

kicad-cli pcb export pos \
  --output positions.csv \
  --format csv \
  --units mm \
  --side front \
  --exclude-dnp \
  project.kicad_pcb

可选参数：

```
--format csv|ascii
```
```
--units mm|in
```
```
--side front|back|both
```
```
--exclude-dnp
```
- 排除不贴装元件

Export 3D Models

导出3D模型

bash

undefined

bash

undefined

STEP format (for mechanical CAD)

STEP格式（用于机械CAD）

kicad-cli pcb export step
--output project.step
--subst-models
project.kicad_pcb

VRML format

VRML格式

kicad-cli pcb export vrml
--output project.wrl
project.kicad_pcb

undefined

kicad-cli pcb export vrml
--output project.wrl
project.kicad_pcb

undefined

Export PDF

导出PDF

bash

kicad-cli pcb export pdf \
  --output pcb.pdf \
  --layers "F.Cu,B.Cu,Edge.Cuts" \
  --black-and-white \
  project.kicad_pcb

bash

kicad-cli pcb export pdf \
  --output pcb.pdf \
  --layers "F.Cu,B.Cu,Edge.Cuts" \
  --black-and-white \
  project.kicad_pcb

Export SVG

导出SVG

bash

kicad-cli pcb export svg \
  --output pcb.svg \
  --layers "F.Cu,Edge.Cuts" \
  --black-and-white \
  project.kicad_pcb

bash

kicad-cli pcb export svg \
  --output pcb.svg \
  --layers "F.Cu,Edge.Cuts" \
  --black-and-white \
  project.kicad_pcb

Export DXF

导出DXF

bash

kicad-cli pcb export dxf \
  --output pcb.dxf \
  --layers "Edge.Cuts" \
  project.kicad_pcb

bash

kicad-cli pcb export dxf \
  --output pcb.dxf \
  --layers "Edge.Cuts" \
  project.kicad_pcb

4. Footprint Commands

4. 封装命令

Export SVG

导出SVG

bash

kicad-cli fp export svg \
  --output footprint.svg \
  footprint.kicad_mod

bash

kicad-cli fp export svg \
  --output footprint.svg \
  footprint.kicad_mod

Upgrade Footprint Library

更新封装库格式

bash

kicad-cli fp upgrade \
  --output ./upgraded/ \
  ./library.pretty/

bash

kicad-cli fp upgrade \
  --output ./upgraded/ \
  ./library.pretty/

5. Symbol Commands

5. 符号库命令

Export SVG

导出SVG

bash

kicad-cli sym export svg \
  --output ./symbols/ \
  library.kicad_sym

bash

kicad-cli sym export svg \
  --output ./symbols/ \
  library.kicad_sym

Upgrade Symbol Library

更新符号库格式

bash

kicad-cli sym upgrade \
  --output upgraded.kicad_sym \
  legacy.lib

bash

kicad-cli sym upgrade \
  --output upgraded.kicad_sym \
  legacy.lib

6. Common Options

6. 通用参数

Option	Description
`--help`	Show command help
`--output` , `-o`	Output file/directory
`--define-var`	Define text variable
`--force` , `-f`	Overwrite existing files

参数	说明
`--help`	显示命令帮助
`--output` , `-o`	指定输出文件/目录
`--define-var`	定义文本变量
`--force` , `-f`	覆盖已有文件

7. Automation Examples

7. 自动化示例

CI/CD Build Script

CI/CD构建脚本

bash

#!/bin/bash
set -euo pipefail

PROJECT="myproject"

bash

#!/bin/bash
set -euo pipefail

PROJECT="myproject"

Run ERC

运行ERC检查

echo "Running ERC..." kicad-cli sch erc
--output reports/erc.rpt
--exit-code-violations
${PROJECT}.kicad_sch

echo "运行ERC检查..." kicad-cli sch erc
--output reports/erc.rpt
--exit-code-violations
${PROJECT}.kicad_sch

Run DRC

运行DRC检查

echo "Running DRC..." kicad-cli pcb drc
--output reports/drc.rpt
--exit-code-violations
${PROJECT}.kicad_pcb

echo "运行DRC检查..." kicad-cli pcb drc
--output reports/drc.rpt
--exit-code-violations
${PROJECT}.kicad_pcb

Generate manufacturing files

生成制造文件

echo "Generating manufacturing files..." mkdir -p output/gerbers

kicad-cli pcb export gerbers
--output output/gerbers/
--layers "F.Cu,B.Cu,F.SilkS,B.SilkS,F.Mask,B.Mask,Edge.Cuts"
${PROJECT}.kicad_pcb

kicad-cli pcb export drill
--output output/gerbers/
--format excellon
${PROJECT}.kicad_pcb

echo "生成制造文件..." mkdir -p output/gerbers

kicad-cli pcb export gerbers
--output output/gerbers/
--layers "F.Cu,B.Cu,F.SilkS,B.SilkS,F.Mask,B.Mask,Edge.Cuts"
${PROJECT}.kicad_pcb

kicad-cli pcb export drill
--output output/gerbers/
--format excellon
${PROJECT}.kicad_pcb

Generate BOM

生成BOM

kicad-cli sch export bom
--output output/bom.csv
--fields "Reference,Value,Footprint,LCSC,MPN"
${PROJECT}.kicad_sch

Generate position file

生成元件位置文件

kicad-cli pcb export pos
--output output/positions.csv
--format csv
--units mm
${PROJECT}.kicad_pcb

echo "Done!"

undefined

kicad-cli pcb export pos
--output output/positions.csv
--format csv
--units mm
${PROJECT}.kicad_pcb

echo "完成！"

undefined

JLCPCB Preparation

JLCPCB生产文件准备脚本

bash

#!/bin/bash
PROJECT="$1"
OUTPUT="./jlcpcb"
mkdir -p "$OUTPUT"

bash

#!/bin/bash
PROJECT="$1"
OUTPUT="./jlcpcb"
mkdir -p "$OUTPUT"

Gerbers (zip for upload)

Gerber文件（压缩后上传）

kicad-cli pcb export gerbers
--output "$OUTPUT/"
--layers "F.Cu,B.Cu,F.SilkS,B.SilkS,F.Mask,B.Mask,Edge.Cuts"
"${PROJECT}.kicad_pcb"

kicad-cli pcb export drill
--output "$OUTPUT/"
--format excellon
--excellon-units mm
"${PROJECT}.kicad_pcb"

cd "$OUTPUT" && zip -r gerbers.zip .g *.drl && cd -

kicad-cli pcb export gerbers
--output "$OUTPUT/"
--layers "F.Cu,B.Cu,F.SilkS,B.SilkS,F.Mask,B.Mask,Edge.Cuts"
"${PROJECT}.kicad_pcb"

kicad-cli pcb export drill
--output "$OUTPUT/"
--format excellon
--excellon-units mm
"${PROJECT}.kicad_pcb"

cd "$OUTPUT" && zip -r gerbers.zip .g *.drl && cd -

BOM for assembly

组装用BOM

kicad-cli sch export bom
--output "$OUTPUT/bom.csv"
--fields "Comment,Designator,Footprint,LCSC"
"${PROJECT}.kicad_sch"

CPL (Component Placement List)

元件位置列表（CPL）

kicad-cli pcb export pos
--output "$OUTPUT/cpl.csv"
--format csv
--units mm
--side front
"${PROJECT}.kicad_pcb"

---

kicad-cli pcb export pos
--output "$OUTPUT/cpl.csv"
--format csv
--units mm
--side front
"${PROJECT}.kicad_pcb"

---

8. Exit Codes

8. 退出码说明

Code	Meaning
0	Success
1	General error
2	DRC/ERC violations found (with --exit-code-violations)

代码	含义
0	执行成功
1	通用错误
2	检测到DRC/ERC违规（使用--exit-code-violations参数时）

9. Important Notes

9. 重要注意事项

What kicad-cli CAN Do

kicad-cli支持的操作

Export files (Gerber, PDF, SVG, netlist, BOM, 3D)
Run validation (DRC, ERC)
Upgrade library formats
Automation and CI/CD

导出各类文件（Gerber、PDF、SVG、网表、BOM、3D模型）
运行规则验证（DRC、ERC）
更新库文件格式
自动化及CI/CD集成

What kicad-cli CANNOT Do

kicad-cli不支持的操作

Modify designs (add components, routes)
Edit schematic/PCB content
Interactive operations

For design modifications, use:

File manipulation (S-expression format)
KiCad Python scripting console
KiCad IPC API (experimental)

Version: This reference is for KiCad 8.x. Commands may differ in older versions.

修改设计内容（添加元件、布线等）
编辑原理图/PCB内容
交互式操作

如需修改设计，可使用：

文件格式处理（S-expression格式）
KiCad Python脚本控制台
KiCad IPC API（实验性）

版本说明： 本参考文档适用于KiCad 8.x版本，旧版本命令可能存在差异。