n8n CLI 快速开始

n8n CLI 是一个轻量级命令行客户端，通过 n8n API 与正在运行的 n8n 实例通信。它可以在任何具备网络访问能力的机器上运行，并使用 API key 进行身份验证。

n8n CLI 处于 beta 阶段

请仅将其用于实验、本地开发和个人项目，不要用于生产工作流。

你可以使用 n8n CLI 来：

• 列出并检查工作流
• 从 JSON 创建工作流
• 查看最近的执行记录
• 创建凭据
• 管理项目

所有操作都会遵循用户权限以及 API key 的作用域限制。

n8n CLI 与 Server CLI

如果你需要管理 n8n 实例本身（例如备份、许可证管理、紧急重置），请参阅 Server CLI。它是一个内置工具，运行在与 n8n 相同的机器上。

方面	n8n CLI	Server CLI
运行位置	任何可访问网络的机器	与 n8n 相同的机器
身份验证	API key	直接访问数据库
是否要求 n8n 运行	是	否（大多数操作不要求）
最适合	开发者、集成、AI 代理	实例运维、备份、应急场景
权限模型	遵循用户角色和 API key 范围	绕过访问控制

安装 n8n-cli

# 通过 npx 直接使用（零安装）
npx @n8n/cli workflow list

# 或全局安装
npm install -g @n8n/cli

连接到实例

n8n-cli config set-url https://your-instance.n8n.cloud
n8n-cli config set-api-key YOUR_API_KEY
n8n-cli config show

• 配置会保存到 ~/.n8n-cli/config.json，并使用受限文件权限（0600）。
• 你可以在 n8n > Settings > n8n API 中获取 API key。

或者，你也可以跳过配置文件，直接使用环境变量：

export N8N_URL=https://your-instance.n8n.cloud
export N8N_API_KEY=your_api_key

内联标志

n8n-cli --url=https://my-n8n.app.n8n.cloud --api-key=n8n_api_xxxxx workflow list

解析顺序

1. 命令行标志（--url、--api-key）
2. 环境变量（N8N_URL、N8N_API_KEY）
3. 配置文件（~/.n8n-cli/config.json）

命令

每个命令都支持 --help 查看详细用法。

主题	命令
workflow	list, get, create, update, delete, activate, deactivate, tags, transfer
execution	list, get, retry, stop, delete
credential	list, get, schema, create, delete, transfer
project	list, get, create, update, delete, members, add-member, remove-member
tag	list, create, update, delete
variable	list, create, update, delete
data-table	list, get, create, delete, rows, add-rows, update-rows, upsert-rows, delete-rows
user	list, get
config	set-url, set-api-key, show
source-control	pull
skill	install
audit	（顶层命令）
login / logout	（顶层命令）

输出格式

所有命令都支持通过 --format 指定三种输出格式：

格式	标志	适用场景
表格	--format=table（默认）	希望获得适合终端阅读的输出
JSON	--format=json	管道到 jq 或进行程序化处理
仅 ID	--format=id-only	管道到 xargs 或编写脚本

示例

• 人类可读的表格输出

n8n-cli workflow list

• 供脚本使用的 JSON

n8n-cli workflow list --format=json | jq '.[] | select(.active) | .id'

• 将 ID 管道到另一个命令

n8n-cli workflow list --format=id-only | xargs -I{} n8n-cli workflow deactivate {}

在 Claude Code 中作为 skill 使用

安装该 skill 后，Claude 会始终知道如何使用 n8n-cli：

n8n-cli skill install --global

然后在 Claude Code 中输入 /n8n-cli 来加载它。此后 Claude 就可以代表你创建、更新和管理工作流，而无需依赖 MCP。

示例

列出并检查工作流

n8n-cli workflow list
n8n-cli workflow get <id>

从 JSON 创建工作流

cat workflow.json | n8n-cli workflow create --stdin

查看最近的执行记录

n8n-cli execution list --status=error --limit=10

创建凭据

n8n-cli credential schema gmailOAuth2  # 先查看所需字段
n8n-cli credential create --type=gmailOAuth2 --name='My Gmail' --file=cred.json

管理项目

n8n-cli project create --name="My Project"
n8n-cli workflow transfer <id> --project=<projectId>