n8n-cli 操作技能

使用 n8n-cli (TypeScript/Bun) 辅助管理工作流的技能。

会话初始化 (重要)

对于新会话，请始终首先运行以下命令，以确保 n8n-cli 是最新的。

优先级 1：从本地源代码构建 (开发环境)

如果 n8n-cli 源代码仓库可通过 add-dir 获得（例如，/path/to/n8n-cli/Makefile 存在），则优先从本地源代码构建，而不是使用发布版本。这可以确保最新的开发变更立即得到反映。

# 如果通过 add-dir 可见 n8n-cli 仓库
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. 导入工作流 (远程 -> 本地)

导入前检查本地格式

将远程内容拉取到本地时，请始终遵循以下步骤：

检查本地文件格式

# 检查文件是否存在及其格式
ls -la definitions/*<workflow-id>* definitions/**/*<workflow-id>*

根据格式使用适当的导入选项
- .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. Dry-run (变更预览)

在应用之前务必使用 dry-run 验证：

# 预览所有工作流的变更
./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

输出示例：

=== CREATE (1 个工作流) ===
  + new-workflow.json (名称: "New Automation")

=== UPDATE (2 个工作流) ===
  ~ existing.json (id: R2cTI0LDzCJSnvNG)
    - name: "Old Name" -> "New Name"
    - nodes: 3 -> 5 nodes

=== SKIP (1 个工作流) ===
  = unchanged.json (无变更)

Summary (dry-run): 1 个将创建，2 个将更新，1 个无变更

4. Apply (部署)

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`	禁用自动标记 (作为代码管理)
`-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

3 路冲突检测：当指定 --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	必需字段 (name、nodes、connections) 检查
`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	节点参数模式验证
`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"
  }
}

配置文件搜索顺序：

使用 --config 标志指定的路径
目标目录中的 .n8nlintrc.json / .n8nlintrc
当前目录中的 .n8nlintrc.json / .n8nlintrc

6. Formatter (自动格式化)

注意：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. Test (执行)

通过测试 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 超时 (默认: 30s)
`--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. Execution (日志和错误)

列出最近的执行记录：

# 列出所有最近的执行记录
./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`	在输出中包含节点执行摘要

显示的错误信息：

字段	描述
错误节点	发生错误的节点
错误消息	错误消息
错误详情	额外的错误描述 (如果有)
最后节点	最后执行的节点

典型的调试工作流程：

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

# 2. 获取特定失败执行的详细信息
./n8n-cli -o table execution get <execution-id> --show-data

# 3. 查看错误详情并修复工作流

9. Convert (格式转换)

在工作流文件之间进行 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-

…

[因原文截断，翻译完成]

ubie-oss/n8n-cli

n8n-cli 是什么？

在你喜欢的 AI 中提问

文档

n8n-cli 操作技能

会话初始化 (重要)

优先级 1：从本地源代码构建 (开发环境)

优先级 2：从 GitHub Releases 自动更新 (推荐)

回退方案：从源码构建

环境设置

检查 .env 文件

创建 .env (仅在需要时)

常用命令

1. 检查远程工作流状态

2. 导入工作流 (远程 -> 本地)

导入前检查本地格式

3. Dry-run (变更预览)

4. Apply (部署)

5. Linter (质量检查)

6. Formatter (自动格式化)

7. Test (执行)

8. Execution (日志和错误)

9. Convert (格式转换)

10. 数据表

相关技能

steipete/notion

langchain-ai/langchain

bytedance/podcast-generation

composiohq/twitter-algorithm-optimizer

composiohq/competitive-ads-extractor

upstash/context7