n8n-cli

n8n-cli 是一个用于管理 n8n 实例的命令行工具，通过 n8n 的 REST API 进行操作。它会自动检测管道输出并切换为 JSON 格式，使其易于在脚本和 LLM 工具中使用。

安装与配置

工具提供三种配置方式：

交互式登录，配置保存到 ~/.n8n-cli/config.json：

n8n-cli login

直接配置：

n8n-cli config set-url https://my-instance.n8n.cloud
n8n-cli config set-api-key n8n_api_...

使用环境变量（无需配置文件）：

export N8N_URL=https://my-instance.n8n.cloud
export N8N_API_KEY=n8n_api_...

全局标志

每个命令都支持以下标志：

--url / -u：实例 URL（覆盖配置/环境变量）
--apiKey / -k：API 密钥（覆盖配置/环境变量）
--format / -f：输出格式，可选 table、json、id-only
--json：等同于 --format=json
--jq：jq 风格过滤器（隐含 --json），例如 '.[0].id'、'.[].name'
--quiet / -q：抑制输出
--no-header：隐藏表头（便于 awk/cut 解析）
--debug：将 HTTP 详情打印到 stderr

当 stdout 被管道传输（非 TTY）时，输出自动默认为 JSON。

主要能力

工作流管理

支持列出、过滤（按激活状态、标签、名称、数量限制）、获取单个工作流（含节点和连接的完整 JSON）、从 JSON 创建、更新、激活/停用、删除、转移到其他项目、列出标签。

执行记录管理

支持列出最近执行记录（可按工作流、状态、数量过滤，状态包括 canceled、error、running、success、waiting）、获取执行详情（可选包含完整节点 I/O）、重试失败执行、停止运行中的执行、删除执行。

凭据管理

支持列出凭据、获取凭据元数据（非密钥）、获取凭据类型的 schema（显示必填字段）、创建凭据（支持 --data、--file、--stdin）、删除、转移。

项目管理

支持列出、获取、创建、更新、删除项目，以及团队成员管理（列出成员、添加成员、移除成员）。

标签管理

支持列出、创建、更新、删除标签。

变量管理

支持列出、创建、更新、删除变量。

数据表管理

支持数据表的增删改查，以及行操作（列出、添加、更新、upsert、删除行），所有行命令支持 --stdin。

用户管理

支持列出用户、获取用户。

项目迁移（Promotions）

通过 Git 仓库在实例之间迁移项目。包含 provider（持有凭据）、connection（命名仓库）、configuration（设置方向：promote 推送到 Git，apply 从 Git 导入）。支持创建 provider（SSH 或 token 认证）、创建 connection、克隆方向、执行 promote/apply、仅应用已审查的提交（通过 --expected-config-id、--expected-branch、--expected-commit-sha 标志）、管理 provider 和 connection、链接项目等。

其他

安全审计：n8n-cli audit，可按类别过滤
源代码控制：n8n-cli source-control pull
查看配置：n8n-cli config show

组合模式

该 CLI 设计为可管道组合，例如：

# 获取所有工作流 ID
n8n-cli workflow list --jq '.[].id'

# 导出工作流到文件
n8n-cli workflow get 1234 --json > workflow-backup.json

# 查找某工作流的失败执行
n8n-cli execution list --workflow=1234 --status=error --json

# 管道修改工作流 JSON
n8n-cli workflow get 1234 --json | jq '.name = "Updated Name"' | n8n-cli workflow update 1234 --stdin

# 无表头表格输出用于 shell 解析
n8n-cli workflow list --no-header | awk '{print $1}'

# 调试 API 调用
n8n-cli workflow list --debug 2>debug.log

工作流 JSON 结构

创建或更新工作流时，JSON 遵循以下结构：

{
  "name": "My Workflow",
  "nodes": [
    {
      "name": "Start",
      "type": "n8n-nodes-base.manualTrigger",
      "position": [250, 300],
      "parameters": {}
    },
    {
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "position": [450, 300],
      "parameters": {
        "url": "https://api.example.com/data",
        "method": "GET"
      }
    }
  ],
  "connections": {
    "Start": {
      "main": [[{ "node": "HTTP Request", "type": "main", "index": 0 }]]
    }
  }
}

要点：

nodes[].type 对内置节点遵循 n8n-nodes-base.<nodeName> 模式
connections 以源节点名称为键，包含 main 输出数组
每个连接指定目标节点、类型（通常为 main）和输出索引
使用 workflow get <id> --json 查看实例中的真实示例

适用场景

适用于需要通过命令行或脚本自动化管理 n8n 实例的场景，包括批量操作工作流、监控和重试执行、管理凭据和项目、在实例间迁移项目、以及将 n8n 操作集成到 LLM 工具调用中。

限制

需要有效的 n8n 实例 URL 和 API 密钥
项目迁移功能需要 Git 仓库和相应的 API 密钥作用域（gitConnection:*，promote 还需要 variable:list）
部分操作（如 apply）在退出码 3（源已更改）或 4（被阻止）时不导入任何内容，需要重新审查或解决冲突
凭据的密钥信息不会通过 get 命令返回，仅返回元数据