---
# System prepended metadata

title: 8. Shell 命令參考
tags: [FlatCAM]

---

# 8. Shell 命令參考

> **警告**
> FlatCAM Shell 功能仍在開發中，未來可能會改變，包含可用命令及其語法。

本文件中語法說明包含命令名稱、參數、參數型態，以及是否為選用或必須參數。所有命令格式如下：

> command\_name <參數1> <參數2> ... \[選用區塊1] \[選用區塊2] ...

命令名稱（command\_name）必須字面輸入且必須在任何參數之前。

參數用「< >」括號標示，為必填參數。輸入時只輸入數值，不包含名稱或括號。文件中可能會標示名稱（供參考）與期望類型（如 str 文字、int 整數、float 浮點數等）。

選用區塊用「\[ ]」方括號表示，括號本身不輸入。若包含選用區塊，區塊內所有元素皆為必填，除非內含更內層的選用子區塊。

選用參數可能是帶名稱的，如 `-outname <str>`，必須字面輸入破折號與名稱後接值，或是一串值如 `x1 [x2 [...]]`，只輸入值。

---

### 8.1. add\_circle

在指定的幾何物件中建立圓形。

> add\_circle <name> \<center\_x> \<center\_y> <radius>

* name：要新增圓形的幾何物件名稱
* center\_x, center\_y：圓心座標
* radius：半徑

---

### 8.2. add\_poly

在指定幾何物件中建立多邊形。

> add\_polygon <str> \[xi, yi <?>]  
> add_poly <str> [xi, yi <?>]

* name <str>：目標幾何物件名稱
* \[xi, yi \<?>]：多邊形頂點座標（可多點）

---

### 8.3. add\_polyline

在指定幾何物件中建立折線。

> add\_polyline <str> \[xi, yi \<?>]

* name <str>：目標幾何物件名稱
* \[xi, yi \<?>]：折線點座標

---

### 8.4. add\_rect

在指定幾何物件中建立矩形。

> add\_rect <name> \<botleft\_x> \<botleft\_y> \<topright\_x> \<topright\_y>

* name：目標幾何物件名稱
* botleft\_x, botleft\_y：左下角座標
* topright\_x, topright\_y：右上角座標

---

### 8.5. aligndrill

建立定位孔鑽孔的 Excellon 檔。

> aligndrill <name> \[-dia <3.0 (float)>] -axis \<X|Y> \[-box <nameOfBox> -minoffset <float> \[-grid <10 (float)> -gridoffset <5 (float)> \[-axisoffset <0 (float)>]] | -dist <number>]

* name：要鏡像的物件名稱（Gerber 或 Excellon）
* dia：刀具直徑
* box：作為區域的物件名稱（例如 cutout）
* grid：對齊格點大小
* gridoffset：格點偏移量
* minoffset：定位孔與 PCB 最小距離
* axisoffset：對齊孔軸第二軸偏移
* axis：鏡像軸，X 或 Y
* dist：鏡像軸與 X 或 Y 軸的距離

---

### 8.6. aligndrillgrid

建立定位孔鑽孔格點。

> aligndrillgrid <outname> \[-dia <3.0 (float)>] -gridx <float> \[-gridoffsetx <0 (float)>] -gridy <float> \[-gridoffsety <0 (float)>] -columns <int> -rows <int>

* outname：輸出物件名稱
* dia：刀具直徑
* gridx, gridy：X、Y 軸格點間距
* gridoffsetx, gridoffsety：X、Y 軸格點偏移量
* columns, rows：X、Y 軸格點數量

---

### 8.7. cncjob

從幾何物件建立 CNC 工作。

> cncjob <str> \[-z\_cut <float>] \[-z\_move <float>] \[-feedrate <float>] \[-tooldia <float>] \[-spindlespeed <int>] \[-multidepth <bool>] \[-depthperpass <float>] \[-outname <str>]

* name：來源物件名稱
* -z\_cut：Z 軸切割高度
* -z\_move：Z 軸移動高度
* -feedrate：切割進給速度
* -tooldia：刀具直徑（顯示用）
* -spindlespeed：主軸轉速（rpm）
* -multidepth：是否使用多層深度切割
* -depthperpass：多層深度切割每層深度
* -outname：輸出物件名稱

---

### 8.8. cutout

建立板材輪廓切割。

> cutout <name> \[-dia <3.0 (float)>] \[-margin <0.0 (float)>] \[-gapsize <0.5 (float)>] \[-gaps \<lr (4|tb|lr)>]

* name：物件名稱
* dia：刀具直徑
* margin：邊距
* gapsize：卡榫大小
* gaps：卡榫類型

---

### 8.9. delete

刪除指定物件。

> delete <name>

* name：物件名稱

---

### 8.10. drillcncjob

從 Excellon 物件建立鑽孔 CNC 工作。

> drillcncjob <str> \[-tools <str>] \[-drillz <float>] \[-travelz <float>] \[-feedrate <float>] \[-spindlespeed <int>] \[-toolchange <bool>] \[-outname <str>]

* name：來源物件名稱
* -tools：刀具索引清單（逗號分隔，如 1,3 或 2），未指定則使用全部刀具
* -drillz：鑽孔深度
* -travelz：鑽孔移動高度
* -feedrate：鑽孔進給速度
* -spindlespeed：主軸轉速
* -toolchange：是否啟用換刀
* -outname：輸出物件名稱

---

### 8.11. export\_gcode

匯出 G-Code 至終端機輸出。

> export\_gcode <str> \[<str>] \[<str>]

* name：來源幾何物件名稱
* preamble：G-Code 頭部附加文字
* postamble：G-Code 尾部附加文字

---

### 8.12. export\_svg

匯出幾何物件為 SVG 檔。

> export\_svg <name> <filename> \[-scale\_factor <0.0 (float)>]

* name：幾何物件名稱
* filename：輸出檔案路徑
* scale\_factor：匯出時縮放線寬比例

---

### 8.13. exteriors

取得多邊形外部邊界。

> exteriors <str> \[-outname <str>]
> ext <str> \[-outname <str>]

* name：來源幾何物件名稱
* outname：輸出物件名稱
* timeout：工作逾時秒數

---

### 8.14. follow

建立追蹤 Gerber 路徑的幾何物件。

> follow <name> \[-outname <oname>]

* name：Gerber 物件名稱
* outname：輸出幾何物件名稱

---

### 8.15. geo\_union

對幾何物件內的所有形狀做聯集。

> geo\_union <name>

* name：幾何物件名稱

---

### 8.16. geocutout

切割幾何物件的卡榫。

> geocutout <name> \[-dia <3.0 (float)>] \[-margin <0.0 (float)>] \[-gapsize <0.5 (float)>] \[-gaps \<lr (8|4|tb|lr|2tb|2lr)>]

* name：幾何物件名稱
* dia：刀具直徑
* margin：邊距
* gapsize：卡榫大小
* gaps：卡榫類型

**範例：**

```bash
# 產生隔離邊界，例如 fritzing arduino shield 或任意 SVG
isolate BCu_margin -dia 3 -overlap 1

# 從隔離物件產生外邊界
exteriors BCu_margin_iso -outname BCu_margin_iso_exterior

# 若不需要，刪除隔離物件
delete BCu_margin_iso

# 最後切割卡榫
geocutout BCu_margin_iso_exterior -dia 3 -gapsize 0.6 -gaps 4
```

---

### 8.17. get\_names

列出專案中所有物件名稱。

> get\_names

無參數。

---

### 8.18. help

顯示命令列表。

---

### 8.19. import\_svg

匯入 SVG 為幾何物件。

> import\_svg <str> \[-type <str>] \[-outname <str>]

* filename：SVG 檔案路徑
* type：匯入為 gerber 或 geometry（預設 geometry）
* outname：輸出物件名稱

---

### 8.20. interiors

取得多邊形內部邊界。

> interiors <str> \[-outname <str>]

* name：來源幾何物件名稱
* outname：輸出物件名稱

---

### 8.21. isolate

建立指定 Gerber 的隔離銑削幾何。

> isolate <str> \[-dia <float>] \[-passes <int>] \[-overlap <float>] \[-combine <int>] \[-outname <str>]

* name：來源物件名稱
* dia：刀具直徑
* passes：通過次數（刀寬倍數）
* overlap：刀具重疊比例
* combine：是否合併所有通過成一幾何物件
* outname：輸出物件名稱

---

### 8.22. join\_excellons

合併多個 Excellon 物件。

> join\_excellons \<out\_name> \<obj\_name\_0>....

* out\_name：新 Excellon 物件名稱
* obj\_name\_0...：要合併的物件名稱列表

---

### 8.23. join\_geometries

合併多個幾何物件。

> join\_geometries \<out\_name> \<obj\_name\_0>....

* out\_name：新幾何物件名稱
* obj\_name\_0...：要合併的物件名稱列表

---

### 8.24. make\_docs

以 reStructuredText 格式列印命令參考。

---

### 8.25. millholes

從 Excellon 建立銑削孔幾何。

> millholes <name> -tools <str> -tooldia <float> -outname <str>

* name：Excellon 物件名稱
* tools：刀具索引（逗號分隔）
* tooldia：銑刀直徑
* outname：輸出物件名稱

---

### 8.26. mirror

鏡像指定層。

> mirror <name> -axis \<X|Y> \[-box <nameOfBox> | -dist <number>]

* name：欲鏡像物件名稱（Gerber 或 Excellon）
* box：當作邊界的物件名稱（例如 cutout）
* axis：鏡像軸，X 或 Y
* dist：鏡像軸距離 X 或 Y 軸的距離

---

### 8.27. new

開始新專案，清除記憶體中的物件。

> new

無參數。

---

### 8.28. new\_geometry

建立新的空白幾何物件。

> new\_geometry <name>

* name：新物件名稱

---

### 8.29. offset

移動物件位置。

> offset <name> <x> <y>

* name：物件名稱
* x：X 軸移動距離
* y：Y 軸移動距離

---

### 8.30. open\_excellon

開啟 Excellon 檔案。

> open\_excellon <filename> \[-outname <o>]

* filename：檔案路徑
* outname：建立的 Excellon 物件名稱

---

### 8.31. open\_gcode

開啟 G-Code 檔案。

> open\_gcode <filename> \[-outname <o>]

* filename：檔案路徑
* outname：建立的 CNC 工作物件名稱

---

### 8.32. open\_gerber

開啟 Gerber 檔案。

> open\_gerber <str> \[-follow <str>] \[-outname <str>]

* filename：檔案路徑
* follow：若為 1，則不建立多邊形，只追蹤 Gerber 路徑
* outname：輸出幾何物件名稱

---

### 8.33. open\_project

開啟 FlatCAM 專案。

> open\_project <filename>

* filename：檔案路徑

---

### 8.34. options

顯示物件設定。

> options <name>

* name：物件名稱

---

### 8.35. paint\_poly

建立刀具路徑以覆蓋多邊形內部。

> paint\_poly <name> \<inside\_pt\_x> \<inside\_pt\_y> <tooldia> <overlap>

* name：來源幾何物件名稱
* inside\_pt\_x, inside\_pt\_y：多邊形內點座標
* tooldia：刀具直徑
* overlap：刀具重疊比例

---

### 8.36. panelize

簡單拼版幾何。

> panelize <name> \[-box <nameOfBox>] \[-spacing\_columns <5 (float)>] \[-spacing\_rows <5 (float)>] -columns <int> -rows <int> \[-outname <n>]

* name：欲拼版物件名稱
* box：作為切割邊界的物件名稱（例如 cutout），未指定則使用 name 物件
* spacing\_columns, spacing\_rows：列與行間距
* columns, rows：列與行數量
* outname：輸出幾何物件名稱

---

### 8.37. plot

更新 GUI 上的繪圖。

---

### 8.38. save\_project

儲存 FlatCAM 專案至檔案。

> save\_project <filename>

* filename：檔案路徑

---

### 8.39. scale

縮放物件尺寸。

> scale <name> <factor>

* name：物件名稱
* factor：縮放倍數

---

### 8.40. set\_active

設定 FlatCAM 物件為活動物件。

> set\_active <name>

* name：物件名稱

---

### 8.41. set\_sys

設定系統參數（FlatCAM 常數）。

> set\_sys <sysparam> <paramvalue>

* sysparam：參數名稱
* paramvalue：設定值

---

### 8.42. subtract\_poly

從幾何物件減去多邊形。

> subtract\_poly <name> <x0> <y0> <x1> <y1> <x2> <y2> \[x3 y3 \[...]]

* name：目標幾何物件名稱
* xi, yi：多邊形頂點座標

---

### 8.43. subtract\_rect

從幾何物件減去矩形。

> subtract\_rect <name> \<botleft\_x> \<botleft\_y> \<topright\_x> \<topright\_y>

* name：目標幾何物件名稱
* botleft\_x, botleft\_y：矩形左下角座標
* topright\_x, topright\_y：矩形右上角座標

---

### 8.44. write\_gcode

將 CNC 工作物件的 G-Code 儲存至檔案。

> write\_gcode <name> <filename>

* name：來源 CNC 工作物件名稱
* filename：輸出檔案名稱

