n8n-cli

A command-line interface for managing n8n workflows as code. Import, export, lint, format, test, and deploy workflow definitions from your terminal.

Features

Apply - Deploy local workflow definitions (JSON/YAML) to an n8n server with dry-run support and conflict detection
Convert - Convert workflow files between JSON and YAML formats locally
Import - Pull workflows from an n8n server to local files, with optional YAML conversion and code externalization
Lint - Validate workflow definitions against configurable rules
Format - Auto-organize node positions for cleaner workflow layouts
Test - Execute CLI tests against workflows via webhook endpoints
Workflow management - List, get, create, update, delete, activate, and deactivate workflows via the n8n API
Execution management - List executions, get execution details, delete, retry, and stop executions
Tag management - List, get, create, update, and delete tags
Credential management - List, get, create, update, delete credentials, get schema, and transfer between projects
Data table management - List, get, create, update, delete data tables and manage rows (insert, update, upsert, delete)
Node schema - Inspect built-in node type schemas (list and dump)
Trace - Analyze data flow and item cardinality through workflow nodes
Git integration - Apply only workflows changed in a Git diff
YAML support - Work with YAML workflow definitions and external code/SQL files
CLAUDE.md integration - Read project settings (default project ID, auto tags, YAML mode) from CLAUDE.md

Installation

Prerequisites

Bun v1.0 or later

Build from source

git clone https://github.com/ubie-oss/n8n-cli.git
cd n8n-cli
bun install
make build

This produces a standalone n8n-cli binary in the project root.

Cross-compile

Build binaries for multiple platforms:

make cross-compile

Outputs are placed in dist/:

n8n-cli-darwin-arm64 (macOS Apple Silicon)
n8n-cli-darwin-x64 (macOS Intel)
n8n-cli-linux-x64 (Linux x64)
n8n-cli-windows-x64 (Windows x64)

Quick Start

Set environment variables for your n8n instance:

export N8N_API_URL="https://your-n8n-instance.example.com"
export N8N_API_KEY="your-api-key"

List workflows:

./n8n-cli workflow list

Import a workflow to a local file:

./n8n-cli import --ids=<workflow-id> --yaml -d ./definitions

Edit the local file and apply changes:

./n8n-cli apply --ids=<workflow-id> --dry-run -d ./definitions
./n8n-cli apply --ids=<workflow-id> -d ./definitions

Commands

`apply`

Deploy local workflow definitions to the n8n server.

n8n-cli apply [options]

Option	Description
`-d, --dir <path>`	Path to definitions directory (default: `./definitions`)
`-p, --project <id>`	Target project ID for workflow transfer
`--ids <ids>`	Comma-separated workflow IDs to process
`--from-git-changes <spec>`	Apply only files changed in Git diff (e.g., `origin/main..HEAD`)
`--dry-run`	Preview changes without applying
`--force`	Override conflict detection and duplicate warnings
`--no-auto-tag`	Disable automatic tagging
`--yaml` / `--no-yaml`	Enable/disable YAML file processing
`--warn-duplicates`	Warn when creating workflows with names that already exist remotely

Exit Codes

Code	Description
`0`	Success
`1`	Error detected
`2`	Conflict detected (dry-run) or warning detected (non-force mode)

`convert`

Convert workflow files between formats (JSON ↔ YAML). This is a local-only operation that does not require an n8n server connection.

n8n-cli convert [options] [files...]

Option	Description
`--format <format>`	Target format: `json`, `yaml` (required)
`-d, --directory <dir>`	Directory to scan for workflow files
`--ids <ids>`	Comma-separated workflow IDs to convert
`--tags <tags>`	Filter by tags (comma-separated, AND condition)
`-t, --threshold <n>`	Minimum lines for code externalization (JSON→YAML)
`--dry-run`	Preview conversions without writing files
`--keep`	Keep original files after conversion

Examples:

# Convert all JSON workflows in a directory to YAML
n8n-cli convert -d ./definitions --format yaml

# Convert specific workflows by ID
n8n-cli convert -d ./definitions --format json --ids wf-100,wf-200

# Preview conversions without making changes
n8n-cli convert -d ./definitions --format yaml --dry-run

# Convert but keep the original files
n8n-cli convert -d ./definitions --format yaml --keep

# Convert a specific file
n8n-cli convert --format yaml workflow__wf-100.json

Behavior:

JSON → YAML: Generates YAML with code externalization (_subfiles/) and description.md
YAML → JSON: Resolves !include directives (inlines external files) and removes _subfiles/ directories
Files already in the target format are skipped
Original files are removed after conversion unless --keep is specified

`import`

Import workflows from n8n to local files.

n8n-cli import [options]

Option	Description
`--dry-run`	Preview changes without writing files
`-d, --dir <directory>`	Target directory for workflow files (default: `./definitions`)
`--ids <ids>`	Comma-separated workflow IDs to import (empty = all)
`--include-archived`	Include archived workflows
`--yaml` / `--no-yaml`	Output as YAML format with external files / Force JSON
`-t, --threshold <n>`	Minimum lines for code externalization
`--cleanup-orphans`	Delete local files without matching remote workflow
`--cleanup-subfiles`	Delete orphan external files
`--tags <tags>`	Filter by tags (comma-separated, AND condition)

`lint`

Lint workflow definition files.

n8n-cli lint [options]

Option	Description
`-d, --dir <directory>`	Directory to scan for workflow files
`-f, --file <files...>`	Specific files to lint
`-c, --config <path>`	Path to `.n8nlintrc.json` config file
`--disable-rule <rules...>`	Disable specific rules
`--list-rules`	List all available rules and exit
`-o, --output <format>`	Output format: `text`, `json` (default: `text`)
`--tags <tags>`	Filter by tags (comma-separated, AND condition)

Lint Configuration (`.n8nlintrc.json`)

Create a .n8nlintrc.json file to configure lint rules. Each rule can be set to:

"error" / "warning" — enable with the specified severity
"off" or false — disable the rule
["error", { ...options }] — enable with severity and rule-specific options

{
  "rules": {
    "orphaned-node": "warning",
    "node-params": "error",
    "webhook-id-required": "off"
  }
}

Lint Rules with Options

`banned-node`

Detects usage of banned node types. Requires the array config format to specify which nodes are banned.

Option	Type	Description
`nodes`	`Array<{ type: string; reason?: string }>`	List of banned node types

type — the node.type identifier (e.g., n8n-nodes-base.executeCommand)
reason — optional; included in the violation message when provided

{
  "rules": {
    "banned-node": ["error", {
      "nodes": [
        { "type": "n8n-nodes-base.executeCommand", "reason": "Security risk: arbitrary command execution" },
        { "type": "n8n-nodes-base.code", "reason": "Use HTTP Request node instead" },
        { "type": "n8n-nodes-base.ssh" }
      ]
    }]
  }
}

`schedule-trigger-frequency`

Validates that Schedule Trigger nodes don't fire more frequently than a configured minimum interval.

Option	Type	Description
`minInterval`	`"minutes"` \| `"hourly"` \| `"daily"` \| `"weekly"` \| `"monthly"`	Minimum allowed trigger interval (default: `"hourly"`)

{
  "rules": {
    "schedule-trigger-frequency": ["warning", { "minInterval": "daily" }]
  }
}

Other Lint Rules

`filter-operator-valid`

Validates that If / Filter node conditions (typeVersion >= 2) use valid operator operations. For example, it flags isNotEmpty and suggests notEmpty instead. Invalid operations silently evaluate to false at runtime, making bugs hard to detect.

Targets: n8n-nodes-base.if, n8n-nodes-base.filter

Enabled by default with severity error.

{
  "rules": {
    "filter-operator-valid": "error"
  }
}

`fmt`

Format workflow files by reorganizing node positions.

n8n-cli fmt [options] [files...]

Option	Description
`--dry-run`	Show changes without saving
`-d, --directory <dir>`	Directory to scan for workflow files
`--tags <tags>`	Filter by tags (comma-separated, AND condition)

`test`

Run CLI test against a workflow via its test webhook.

n8n-cli test <workflow-id> [options]

Option	Description
`-d, --data <json>`	JSON data to send to the webhook
`--timeout <ms>`	HTTP request timeout in milliseconds (default: 30000)
`--wait-execution`	Wait for execution to complete and show results
`--execution-timeout <ms>`	Max time to wait for execution (default: 300000)
`--activate`	Automatically activate the workflow if inactive
`--dry-run`	Show webhook URL without executing
`--show-inputs`	Display workflow input parameters without executing

`workflow`

Manage n8n workflows.

n8n-cli workflow <subcommand>

`workflow list`

List all workflows.

Option	Description
`--active`	List only active workflows
`--inactive`	List only inactive workflows
`--tags <tags>`	Filter by tags (comma-separated)
`--limit <n>`	Maximum number of workflows to return (0 = all, default: `0`)

`workflow get <id>`

Get a workflow by ID.

Option	Description
`-f, --file <path>`	Output file path (writes JSON to file)

`workflow create`

Create a new workflow.

Option	Description
`-f, --file <path>`	Path to workflow JSON file, use `-` for stdin (required)

`workflow update [id]`

Update an existing workflow. The ID argument is optional if the JSON file contains an id field.

Option	Description
`-f, --file <path>`	Path to workflow JSON file, use `-` for stdin (required)
`--force`	Force update even if remote has been modified

`workflow delete <ids...>`

Delete one or more workflows.

Option	Description
`--force`	Skip confirmation prompt

`workflow activate <id>`

Activate a workflow.

`workflow deactivate <id>`

Deactivate a workflow.

`execution`

Manage n8n workflow executions.

n8n-cli execution <subcommand>

Subcommand	Description
`list`	List workflow executions
`get <id>`	Get execution details by ID
`delete <id>`	Delete an execution by ID
`retry <id>`	Retry a failed execution
`stop <id>`	Stop a running execution

`execution list`

n8n-cli execution list [options]

Option	Description
`-w, --workflow <id>`	Filter by workflow ID
`-s, --status <status>`	Filter by status (`success`, `error`, `running`, `waiting`)
`-l, --limit <n>`	Maximum number of executions to return (default: 20)

`execution get`

n8n-cli execution get <id> [options]

Option	Description
`--show-data`	Include node execution summary in output

Output includes:

Execution ID, workflow ID, status, mode
Start and stop timestamps
Error details (node, message, description) if the execution failed
Node execution summary (with --show-data)

`execution delete`

Delete an execution by ID.

n8n-cli execution delete <id>

`execution retry`

Retry a failed execution.

n8n-cli execution retry <id>

`execution stop`

Stop a running execution.

n8n-cli execution stop <id>

`tag`

Manage n8n tags.

n8n-cli tag <subcommand>

Subcommand	Description
`list`	List all tags
`get <id>`	Get a tag by ID
`create <name>`	Create a new tag
`update <id>`	Update an existing tag
`delete <ids...>`	Delete one or more tags

`tag list`

n8n-cli tag list [options]

Option	Description
`-l, --limit <n>`	Maximum number of tags to return

`tag get`

Get a tag by ID.

n8n-cli tag get <id>

`tag create`

Create a new tag.

n8n-cli tag create <name>

`tag update`

Update an existing tag.

n8n-cli tag update <id> [options]

Option	Description
`-n, --name <name>`	New tag name (required)

`tag delete`

Delete one or more tags.

n8n-cli tag delete <ids...> [options]

Option	Description
`--force`	Skip confirmation prompt

`credential`

Manage n8n credentials.

n8n-cli credential <subcommand>

Subcommand	Description
`list`	List all credentials
`get <id>`	Get a credential by ID
`create`	Create a new credential
`update <id>`	Update an existing credential
`delete <ids...>`	Delete one or more credentials
`schema <typeName>`	Get the schema for a credential type
`transfer <id>`	Transfer a credential to a different project

`credential list`

n8n-cli credential list [options]

Option	Description
`-l, --limit <n>`	Maximum number of credentials to return

`credential get`

Get a credential by ID.

n8n-cli credential get <id>

`credential create`

Create a new credential.

n8n-cli credential create [options]

Option	Description
`-n, --name <name>`	Credential name (required)
`-t, --type <type>`	Credential type, e.g., `slackApi` (required)
`-d, --data <json>`	Credential data as JSON string (required)

`credential update`

Update an existing credential.

n8n-cli credential update <id> [options]

Option	Description
`-n, --name <name>`	New credential name
`-t, --type <type>`	New credential type
`-d, --data <json>`	New credential data as JSON string

`credential delete`

Delete one or more credentials.

n8n-cli credential delete <ids...> [options]

Option	Description
`--force`	Skip confirmation prompt

`credential schema`

Get the schema for a credential type.

n8n-cli credential schema <typeName>

`credential transfer`

Transfer a credential to a different project.

n8n-cli credential transfer <id> [options]

Option	Description
`-p, --project <projectId>`	Destination project ID (required)

`data-tables`

Manage n8n data tables and their rows.

n8n-cli data-tables <subcommand>

Subcommand	Description
`list`	List all data tables
`get <id>`	Get a data table by ID
`create`	Create a new data table
`update <id>`	Update an existing data table
`delete <ids...>`	Delete one or more data tables
`rows list <dataTableId>`	List rows in a data table
`rows insert <dataTableId>`	Insert rows into a data table
`rows update <dataTableId>`	Update rows in a data table
`rows upsert <dataTableId>`	Upsert rows in a data table
`rows delete <dataTableId>`	Delete rows from a data table

`data-tables list`

n8n-cli data-tables list [options]

Option	Description
`-l, --limit <n>`	Maximum number of data tables to return
`--filter <json>`	Filter as JSON string
`--sort-by <field:dir>`	Sort by field and direction (e.g., `name:asc`)

`data-tables get`

Get a data table by ID, including column definitions.

n8n-cli data-tables get <id>

`data-tables create`

Create a new data table with column definitions.

n8n-cli data-tables create [options]

Option	Description
`-n, --name <name>`	Data table name (required)
`-c, --columns <json>`	Columns as JSON array (required), e.g., `'[{"name":"col1","type":"string"}]'`

Supported column types: string, number, boolean, date, json.

`data-tables update`

Update an existing data table (name only).

n8n-cli data-tables update <id> [options]

Option	Description
`-n, --name <name>`	New data table name (required)

`data-tables delete`

Delete one or more data tables.

n8n-cli data-tables delete <ids...> [options]

Option	Description
`--force`	Skip confirmation prompt

`data-tables rows list`

List rows in a data table.

n8n-cli data-tables rows list <dataTableId> [options]

Option	Description
`-l, --limit <n>`	Maximum number of rows to return
`--filter <json>`	Filter as JSON string
`--sort-by <field:dir>`	Sort by field and direction
`--search <text>`	Search text

`data-tables rows insert`

Insert rows into a data table.

n8n-cli data-tables rows insert <dataTableId> [options]

Option	Description
`-d, --data <json>`	Row data as JSON array (required), e.g., `'[{"col1":"value"}]'`
`--return-type <type>`	Return type: `count`, `id`, or `all` (default: `count`)

`data-tables rows update`

Update rows matching a filter.

n8n-cli data-tables rows update <dataTableId> [options]

Option	Description
`--filter <json>`	Filter as JSON string (required)
`-d, --data <json>`	Update data as JSON object (required)
`--return-data`	Return updated data
`--dry-run`	Dry run without making changes

`data-tables rows upsert`

Upsert rows matching a filter.

n8n-cli data-tables rows upsert <dataTableId> [options]

Option	Description
`--filter <json>`	Filter as JSON string (required)
`-d, --data <json>`	Upsert data as JSON object (required)
`--return-data`	Return upserted data
`--dry-run`	Dry run without making changes

`data-tables rows delete`

Delete rows matching a filter.

n8n-cli data-tables rows delete <dataTableId> [options]

Option	Description
`--filter <json>`	Filter as JSON string (required)
`--return-data`	Return deleted data
`--dry-run`	Dry run without making changes
`--force`	Skip confirmation prompt

`node-schema`

Inspect built-in node type schemas.

n8n-cli node-schema <subcommand>

Subcommand	Description
`list`	List all built-in node types
`dump`	Dump full node schema definitions

`node-schema list`

n8n-cli node-schema list [options]

Option	Description
`--output <format>`	Output format: `table`, `json` (default: `table`)
`--group <name>`	Filter by group name (e.g., `trigger`, `transform`)

`node-schema dump`

n8n-cli node-schema dump [options]

Option	Description
`--type <nodeType>`	Dump a specific node type (e.g., `n8n-nodes-base.slack`)
`-o, --output-dir <dir>`	Dump all nodes as individual JSON files to a directory

Prerequisites: Requires n8n-nodes-base and @n8n/n8n-nodes-langchain in node_modules.

`trace`

Analyze data flow and item cardinality through workflow nodes.

n8n-cli trace [options]

Option	Description
`-d, --dir <directory>`	Directory to scan for workflow files
`-f, --file <files...>`	Specific files to trace
`--json`	Output in JSON format
`--tags <tags>`	Filter by tags (comma-separated, AND condition)

Output columns:

Column	Description
Node	Node name
Type	n8n node type
Cardinality	Output cardinality: `1:1`, `1:N`, `N:1`, `pass-through`, `variable`, `unknown`
Items	Estimated output item count
Inputs	Upstream nodes
Outputs	Downstream nodes

`version`

Show version information including version, git commit, build date, runtime (Bun version), and OS/Arch.

n8n-cli version
# n8n-cli version 1.0.0
#   Git commit: abc1234
#   Built:      2025-01-01T00:00:00Z
#   Runtime:    Bun 1.x.x
#   OS/Arch:    darwin/arm64

Global Options

Option	Description
`--api-url <url>`	n8n API URL (env: `N8N_API_URL`)
`--api-key <key>`	n8n API key (env: `N8N_API_KEY`)
`--timeout <duration>`	Request timeout, e.g. `30s`, `5m` (env: `N8N_API_TIMEOUT`)
`-o, --output <format>`	Output format: `json`, `table` (default: `json`)

Configuration

Environment Variables

Variable	Description
`N8N_API_URL`	n8n instance API URL (required)
`N8N_API_KEY`	n8n API key (required)
`N8N_API_TIMEOUT`	Request timeout in milliseconds
`N8N_DEFAULT_PROJECT`	Default project ID for apply
`APPLY_FILTER_BY_TAGS`	Comma-separated tags to filter apply targets
`CHECKS_FILTER_BY_TAGS`	Comma-separated tags to filter lint/fmt targets (AND condition)

CLAUDE.md Integration

n8n-cli can read project settings from a CLAUDE.md file in your repository:

Default project ID - Automatically set the target project for apply
Auto tags - Tags to automatically add to deployed workflows
YAML mode - Enable/disable YAML processing by default
Externalize threshold - Minimum lines for code externalization during import

Documentation

See the docs/ directory for additional documentation.

Contributing

See CONTRIBUTING.md for development setup, build instructions, and contribution guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
.claude/skills/n8n-cli		.claude/skills/n8n-cli
.github/workflows		.github/workflows
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
biome.json		biome.json
bun.lock		bun.lock
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

n8n-cli

Features

Installation

Prerequisites

Build from source

Cross-compile

Quick Start

Commands

apply

Exit Codes

convert

import

lint

Lint Configuration (.n8nlintrc.json)

Lint Rules with Options

banned-node

schedule-trigger-frequency

Other Lint Rules

filter-operator-valid

fmt

test

workflow

workflow list

workflow get <id>

workflow create

workflow update [id]

workflow delete <ids...>

workflow activate <id>

workflow deactivate <id>

execution

execution list

execution get

execution delete

execution retry

execution stop

tag

tag list

tag get

tag create

tag update

tag delete

credential

credential list

credential get

credential create

credential update

credential delete

credential schema

credential transfer

data-tables

data-tables list

data-tables get

data-tables create

data-tables update

data-tables delete

data-tables rows list

data-tables rows insert

data-tables rows update

data-tables rows upsert

data-tables rows delete

node-schema

node-schema list

node-schema dump

trace

version

Global Options

Configuration

Environment Variables

CLAUDE.md Integration

Documentation

Contributing

License

About

Topics

Resources

License

`apply`

`convert`

`import`

`lint`

Lint Configuration (`.n8nlintrc.json`)

`banned-node`

`schedule-trigger-frequency`

`filter-operator-valid`

`fmt`

`test`

`workflow`

`workflow list`

`workflow get <id>`

`workflow create`

`workflow update [id]`

`workflow delete <ids...>`

`workflow activate <id>`

`workflow deactivate <id>`

`execution`

`execution list`

`execution get`

`execution delete`

`execution retry`

`execution stop`

`tag`

`tag list`

`tag get`

`tag create`

`tag update`

`tag delete`

`credential`

`credential list`

`credential get`

`credential create`

`credential update`

`credential delete`

`credential schema`

`credential transfer`

`data-tables`

`data-tables list`

`data-tables get`

`data-tables create`

`data-tables update`

`data-tables delete`

`data-tables rows list`

`data-tables rows insert`

`data-tables rows update`

`data-tables rows upsert`

`data-tables rows delete`

`node-schema`

`node-schema list`

`node-schema dump`

`trace`

`version`

Packages