n8n-cli 工作技能

n8n-cli 操作技能

一個使用 n8n-cli (TypeScript/Bun) 來管理工作流程的技能。

工作階段初始化 (重要)

對於新的工作階段，請務必先執行以下步驟，以確保 n8n-cli 是最新版本。

優先級 1：從本機原始碼建置 (開發環境)

如果可透過 add-dir 取得 n8n-cli 原始碼儲存庫 (例如 /path/to/n8n-cli/Makefile 存在)，則從本機原始碼建置，而不是使用發行版本。這可以確保最新的開發變更能立即反映。

# 如果 n8n-cli 儲存庫可透過 add-dir 看到
N8N_CLI_REPO="/path/to/n8n-cli"  # 替換為 add-dir 路徑
if [ -f "$N8N_CLI_REPO/Makefile" ]; then
  echo "從本機原始碼建置 n8n-cli: $N8N_CLI_REPO"
  cd "$N8N_CLI_REPO" && bun install && make build
  cp "$N8N_CLI_REPO/n8n-cli" /path/to/target/n8n-cli
  cd /path/to/target
  echo "已從本機原始碼建置: $(./n8n-cli version 2>/dev/null | head -1)"
fi

優先級 2：從 GitHub Releases 自動更新 (建議)

GitHub Releases 上提供了預先建置的二進位檔。這比從原始碼建置更快，並確保您執行的是官方版本。

# 1. 檢查最新版本
LATEST_TAG=$(gh release view --repo ubie-oss/n8n-cli --json tagName -q '.tagName' 2>/dev/null)

# 2. 檢查目前本機版本 (如果二進位檔存在)
CURRENT_VERSION=""
if [ -x ./n8n-cli ]; then
  CURRENT_VERSION=$(./n8n-cli version 2>/dev/null | head -1 | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "")
fi

# 3. 比較並在下載
if [ -z "$CURRENT_VERSION" ] || [ "$CURRENT_VERSION" != "$LATEST_TAG" ]; then
  echo "更新 n8n-cli: ${CURRENT_VERSION:-none} -> ${LATEST_TAG}"

  # 偵測平台
  ARCH=$(uname -m)
  OS=$(uname -s | tr '[:upper:]' '[:lower:]')
  case "$ARCH" in
    arm64|aarch64) ASSET_NAME="n8n-cli-${OS}-arm64" ;;
    x86_64)        ASSET_NAME="n8n-cli-${OS}-x64" ;;
    *)             echo "不支援的架構: $ARCH"; exit 1 ;;
  esac

  # 下載二進位檔
  gh release download "$LATEST_TAG" --repo ubie-oss/n8n-cli --pattern "$ASSET_NAME" --output n8n-cli --clobber
  chmod +x ./n8n-cli
  echo "已更新至 $(./n8n-cli version 2>/dev/null | head -1)"
else
  echo "n8n-cli 已是最新版本: $CURRENT_VERSION"
fi

備用方案：從原始碼建置

如果 gh CLI 不可用，或者您需要開發版本：

# 安裝相依套件 + 建置 CLI
bun install && make build

建置驗證：

./n8n-cli version

環境設定

檢查 .env 檔案

如果 .env 存在於專案根目錄，則 n8n-cli 可以在不指定參數的情況下使用。 請勿讀取內容。

# 僅檢查 .env 是否存在 (不讀取內容)
test -f .env && echo ".env 存在 - n8n-cli 可以在不帶參數的情況下使用"

如果 .env 存在：

• N8N_API_URL 和 N8N_API_KEY 已經設定
• ./n8n-cli 可以在不帶參數的情況下執行

如果 .env 不存在：

• 提示使用者建立 .env 檔案
• 或者使用 --api-url 和 --api-key 標誌

建立 .env (僅在需要時)

cp .env.example .env
# 請使用者編輯

常用指令

1. 檢查遠端工作流程狀態

檢查特定的工作流程：

# 依 ID 取得工作流程資訊
./n8n-cli workflow get <workflow-id>

# 以表格格式顯示以便閱讀
./n8n-cli -o table workflow get <workflow-id>

# 儲存到檔案 (便於進行差異比較)
./n8n-cli workflow get <workflow-id> > /tmp/remote-workflow.json

列出工作流程：

# 所有工作流程
./n8n-cli workflow list

# 表格格式
./n8n-cli -o table workflow list

# 僅活躍中的
./n8n-cli workflow list --active

2. 匯入工作流程 (遠端 -> 本機)

在匯入前檢查本機格式

將遠端內容拉取到本機時，請務必遵循以下步驟：

1. 檢查本機檔案格式

   # 檢查檔案是否存在及其格式
   ls -la definitions/*<workflow-id>* definitions/**/*<workflow-id>*
   

2. 根據格式使用適當的匯入選項

   • .json 檔案：僅使用 --ids
   • .yaml/.yml 檔案：同時使用 --ids 和 --yaml

匯入特定的工作流程：

# JSON 格式工作流程
./n8n-cli import --ids=<workflow-id>

# YAML 格式工作流程
./n8n-cli import --ids=<workflow-id> --yaml

# 匯入到自訂目錄
./n8n-cli import --ids=<workflow-id> -d ./my-dir

匯入多個工作流程：

# 逗號分隔清單
./n8n-cli import --ids=abc123,def456,ghi789

匯入所有工作流程：

./n8n-cli import

其他選項：

選項	描述
--include-archived	包含已封存的工作流程
--cleanup-orphans	刪除沒有比對 ID 的孤立檔案
-t, --threshold <int>	外部檔案擷取的最小行數 (預設: 0，可在 CLAUDE.md 中設定)
--dry-run	僅預覽 (不變更檔案)
--tags <tags>	以逗號分隔的標籤名稱進行篩選 (AND 條件)

3. 試執行 (變更預覽)

在套用變更前，請務必使用試執行驗證：

# 預覽所有工作流程的變更
./n8n-cli apply --dry-run

# 僅預覽特定的工作流程 (依 ID)
./n8n-cli apply --dry-run --ids=<workflow-id>

# 僅預覽特定檔案
./n8n-cli apply --dry-run -d definitions/path/to/workflow.json

輸出範例：

=== 建立 (1 個工作流程) ===
  + new-workflow.json (名稱: "New Automation")

=== 更新 (2 個工作流程) ===
  ~ existing.json (id: R2cTI0LDzCJSnvNG)
    - name: "Old Name" -> "New Name"
    - nodes: 3 -> 5 個節點

=== 略過 (1 個工作流程) ===
  = unchanged.json (無變更)

摘要 (試執行): 1 個將建立, 2 個將更新, 1 個不變

4. 套用 (佈署)

AI 助手必須始終使用 --ids

# 僅套用特定工作流程 (建議)
./n8n-cli apply --ids=<workflow-id>

# 僅套用特定檔案
./n8n-cli apply -d definitions/path/to/workflow.json

# 強制套用 (覆寫遠端變更)
./n8n-cli apply --ids=<workflow-id> --force

禁止：套用到整個目錄

# AI 不得執行這些指令
./n8n-cli apply -d definitions/
./n8n-cli apply

其他選項：

選項	描述
--from-git-changes <spec>	僅套用 Git diff 中變更的檔案
--yaml / --no-yaml	啟用/停用 YAML 處理
--allow-duplicates	略過上游重複名稱檢查 (預設: 開啟；使用 --force 強制通過警告，而不是停用檢查)
--no-auto-tag	停用自動標記 (managed-as-code)
-p, --project <id>	指定目標專案 ID

環境變數：

• APPLY_FILTER_BY_TAGS - 以逗號分隔的標籤名稱進行篩選 (AND 條件)

Git diff 模式：

# 僅套用來自功能分支的變更
./n8n-cli apply --from-git-changes origin/main..HEAD

# 預覽
./n8n-cli apply --from-git-changes origin/main..HEAD --dry-run

# 來自最後 3 次提交的變更
./n8n-cli apply --from-git-changes HEAD~3..HEAD

三方衝突偵測：指定 --from-git-changes 時，會透過比較 Base (參考點)、Local (目前) 和 Remote (伺服器) 來偵測衝突，以識別出真正的衝突。

5. Linter (程式碼品質檢查)

Linter 已整合到 CLI 中。無需單獨建置。

注意：不支援位置引數。請務必使用 -f 或 -d 指定檔案/目錄。

# 檢查特定的檔案 (-f 必要)
./n8n-cli lint -f definitions/<filename>

# 檢查特定的目錄
./n8n-cli lint -d ./definitions/example-project

# 檢查所有工作流程
./n8n-cli lint -d ./definitions

# JSON 輸出 (適用於 CI/CD)
./n8n-cli lint -d ./definitions -o json

選項：

選項	描述
-d, --dir <path>	定義檔目錄
-f, --file <files...>	特定的檔案
-c, --config <path>	設定檔路徑 (.n8nlintrc.json)
--disable-rule <name>	停用特定的規則
--list-rules	列出所有規則
-o, --output <format>	輸出格式：text, json (預設: text)

規則 (11 條規則)：

規則	嚴重性	描述
json-syntax	error	JSON 語法檢查
required-fields	error	必要欄位 (名稱, 節點, 連線) 檢查
connection-reference	error	連線目標節點存在性檢查
webhook-id-required	error	檢查 webhook 和 formTrigger 節點是否具有 webhookId 欄位
orphaned-node	warning	孤兒節點偵測
implicit-json-ref	warning	隱含 $json 參照偵測
expression-mode-prefix	warning	缺少 = 前綴偵測
ai-agent-output-ref	warning	AI Agent 輸出錯誤參照偵測
node-params	warning	節點參數 schema 驗證
node-ref-field-check	warning	參照欄位存在性驗證
node-ref-cardinality	warning	.item/.first() 使用方式驗證

設定檔 (.n8nlintrc.json)：

{
  "rules": {
    "json-syntax": "error",
    "required-fields": "error",
    "orphaned-node": "warning",
    "implicit-json-ref": "off"
  }
}

設定檔搜尋順序：

1. 使用 --config 標誌指定的路徑
2. 目標目錄中的 .n8nlintrc.json / .n8nlintrc
3. 目前目錄中的 .n8nlintrc.json / .n8nlintrc

6. 格式化工具 (自動格式化)

注意：fmt 接受位置引數作為檔案 (沒有 -f 選項)。

# 格式化特定的檔案 (位置引數)
./n8n-cli fmt definitions/<filename>

# 多個檔案
./n8n-cli fmt definitions/file1.yaml definitions/file2.yaml

# 格式化整個目錄
./n8n-cli fmt -d ./definitions

# 僅預覽
./n8n-cli fmt -d ./definitions --dry-run

7. 測試 (執行)

透過測試 Webhook 測試工作流程：

# 基本測試
./n8n-cli test <workflow-id>

# 使用測試資料
./n8n-cli test <workflow-id> -d '{"email": "[email protected]"}'

# 等待執行完成 (建議)
./n8n-cli test <workflow-id> --wait-execution

# 自動啟用非活躍中的工作流程
./n8n-cli test <workflow-id> --activate

# 僅檢查 Webhook URL
./n8n-cli test <workflow-id> --dry-run

# 檢查輸入參數
./n8n-cli test <workflow-id> --show-inputs

選項：

選項	描述
-d, --data <json>	測試資料 (JSON 字串)
--timeout <duration>	HTTP 逾時 (預設: 30 秒)
--wait-execution	等待執行完成並顯示結果
--activate	自動啟用非活躍中的工作流程
--dry-run	僅檢查 Webhook URL
--show-inputs	顯示輸入參數
-o, --output <fmt>	輸出格式: json, table (預設: json)

從本機檔案進行測試：

# 指定本機 JSON/YAML 檔案
./n8n-cli test ./definitions/my-workflow.json

8. 執行 (記錄與錯誤)

列出最近的執行記錄：

# 列出所有最近的執行記錄
./n8n-cli execution list

# 以表格格式顯示以便閱讀
./n8n-cli -o table execution list

# 依狀態篩選
./n8n-cli execution list --status error
./n8n-cli execution list --status success

# 依工作流程篩選
./n8n-cli execution list --workflow <workflow-id>

# 限制結果數量
./n8n-cli execution list --limit 5

# 組合篩選
./n8n-cli execution list --workflow <workflow-id> --status error --limit 10

取得執行詳細資訊：

# 依 ID 取得執行記錄
./n8n-cli execution get <execution-id>

# 表格格式並包含錯誤詳細資訊
./n8n-cli -o table execution get <execution-id>

# 包含節點執行摘要
./n8n-cli -o table execution get <execution-id> --show-data

execution list 的選項：

選項	描述
-w, --workflow <id>	依工作流程 ID 篩選
-s, --status <status>	依狀態篩選 (success, error, running, waiting)
-l, --limit <n>	最大執行記錄數 (預設: 20)

execution get 的選項：

選項	描述
--show-data	在輸出中包含節點執行摘要

顯示的錯誤資訊：

欄位	描述
Error Node	發生錯誤的節點
Error Message	錯誤訊息
Error Details	其他錯誤描述 (如果有的話)
Last Node	最後執行的節點

典型的除錯工作流程：

# 1. 列出最近的錯誤
./n8n-cli -o table execution list --status error --limit 5

# 2. 取得特定失敗執行的詳細資訊
./n8n-cli -o table execution get <execution-id> --show-data

# 3. 檢閱錯誤詳細資訊並修復工作流程

9. 轉換 (格式轉換)

在工作流程檔案之間轉換 JSON 和 YAML 格式 (僅限本機，無需 API)：

# 將所有 JSON 工作流程轉換為 YAML
./n8n-cli convert -d ./definitions --format yaml

# 依 ID 轉換特定的工作流程
./n8n-cli convert -d ./definitions --format json --ids <workflow-id>

# 預覽但不寫入
./n8n-cli convert -d ./definitions --format yaml --dry-run

# 保留原始檔案
./n8n-cli convert -d ./definitions --format yaml --keep

# 轉換單一檔案
./n8n-cli convert --format yaml definitions/<filename>.json

選項：

選項	描述
--format <format>	目標格式：json, yaml (必要)
-d, --directory <dir>	掃描工作流程檔案的目錄
--ids <ids>	以逗號分隔的要轉換的工作流程 ID
--tags <tags>	依標籤篩選 (逗號分隔, AND 條件)
-t, --threshold <n>	程式碼外部化的最小行數 (JSON→YAML)
--dry-run	僅預覽
--keep	保留原始檔案

行為：

• JSON→YAML：產生 YAML + 帶有外部化程式碼的 _subfiles/
• YAML→JSON：解析 !include 參照並移除 _subfiles/
• 已為目標格式的檔案將被略過
• 轉換後會移除原始檔案，除非指定 --keep

10. 資料表格

管理資料表格和資料列：

# 列出所有資料表格
./n8n-

[因原文截斷，此處結尾不完整]