n8n-cli

v1.9.1

Published

18 days ago

Full-featured n8n CLI - workflow management, validation, node search, and more

0High
0Medium
0Low

yigitkonur

n8n workflow validation cli automation nodes templates executions

Part 1: Getting Started

Part 2: Configuration

Configuration

Part 3: Command Reference

Part 4: Advanced Usage

Part 5: Reference & Support

Why Agent-First?

This CLI is designed from the ground up for AI agents that generate n8n workflows programmatically. Instead of streaming large JSON through tool calls (which causes token limits and hallucinations), agents can leverage a local-first architecture:

The Agent Development Loop

┌─────────────────────────────────────────────────────────────────────────────┐
│                         AGENT DEVELOPMENT LOOP                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌─────────────┐    ┌─────────────────┐    ┌──────────────────────────┐   │
│   │ 1. GENERATE │───▶│ 2. WRITE FILE   │───▶│ 3. VALIDATE LOCALLY      │   │
│   │   Workflow  │    │   workflow.json │    │   n8n workflows validate │   │
│   └─────────────┘    └─────────────────┘    └───────────┬──────────────┘   │
│                                                         │                   │
│                                                         ▼                   │
│   ┌─────────────┐    ┌─────────────────┐    ┌──────────────────────────┐   │
│   │ 6. DEPLOY   │◀───│ 5. ITERATE      │◀───│ 4. GET STRUCTURED ERRORS │   │
│   │   to n8n    │    │   Fix Issues    │    │   with schema hints      │   │
│   └─────────────┘    └─────────────────┘    └──────────────────────────┘   │
│                                                                             │
│   Tight local loop • No network latency • Instant validation feedback       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Generate — Agent creates workflow JSON based on user requirements
Write — Save workflow to local file: workflow.json
Validate — Run n8n workflows validate workflow.json --json
Get Errors — Receive structured errors with correctUsage showing exact schema
Iterate — Fix issues locally (no network latency, no API rate limits)
Deploy — Once valid: n8n workflows import workflow.json --json

Key Design Principles

| Principle | Implementation | Benefit | |-----------|----------------|---------| | JSON Everywhere | Every command supports --json flag | Machine-readable output for automation | | Schema Hints | Validation errors include correctUsage | Agents know exactly what structure to use | | Offline First | 800+ nodes bundled in SQLite database | No API needed for node lookup/validation | | POSIX Exit Codes | Standard exit codes (0, 64, 65, 70, etc.) | Reliable scripting and error handling | | Predictable Structure | n8n <resource> <action> [options] | Consistent command patterns |

Feature Overview

| Feature | Description | Use Case | |---------|-------------|----------| | Workflow Validation | Schema-aware validation with 4 profiles | Catch errors before deployment | | Expression Validation | Detects missing = prefix in {{ }} | Fix common AI mistakes | | AI Node Validation | 15+ checks for AI Agent workflows | Validate LLM/tool connections | | Node Type Suggestions | Fuzzy matching for typos | Auto-fix httprequest → n8n-nodes-base.httpRequest | | Autofix Engine | 8 fix types with confidence levels | Automated issue resolution | | Version Management | Local version history with rollback | Safe iteration on workflows | | Diff Operations | 17 surgical modification types | Update without full replacement | | Template Deployment | One-command template deploy | n8n workflows deploy-template 3121 | | Breaking Changes | Version migration analysis | Understand upgrade impacts | | Offline Node Search | FTS5 full-text search | Find nodes without API |

Target Audience

| Audience | Primary Use Case | Key Features | |----------|------------------|--------------| | 🤖 AI Agents (Primary) | Workflow generation & deployment | JSON output, schema hints, offline validation | | 👨‍💻 DevOps Engineers | CI/CD pipeline integration | Exit codes, scripting support, bulk operations | | ⚡ n8n Power Users | Advanced workflow management | Version control, diff operations, autofix | | 🔧 Automation Builders | Template-based development | Template search, deploy, customize |

What Sets This CLI Apart

| Approach | n8n Web UI | Raw API Calls | n8n-cli | |----------|------------|---------------|-------------| | Validation | Runtime only | None | Pre-deployment with hints | | Node Lookup | Requires login | Requires API | 800+ nodes offline | | Error Feedback | Visual in UI | Raw HTTP errors | Structured JSON with fixes | | Batch Operations | Manual one-by-one | Custom scripting | Built-in bulk commands | | Version Control | None | Manual | Automatic versioning | | AI Integration | Not designed for | Token-heavy | Native JSON support |

💡 Tip: For AI agents, start with n8n nodes search to discover available nodes, then n8n nodes show <type> --detail minimal --json to get token-efficient schemas.

Installation

Requirements

| Requirement | Minimum Version | Notes | |-------------|-----------------|-------| | Node.js | 18.0.0 | LTS versions recommended | | npm/yarn/pnpm | Any recent version | Package manager of choice | | Operating System | macOS, Linux, Windows | All platforms supported |

Installation Methods

Option 1: Run Directly with npx (No Installation)

# Run any command without installing
npx n8n-cli --help
npx n8n-cli nodes search "slack"
npx n8n-cli workflows validate workflow.json --json

💡 Best for: Quick testing, CI/CD pipelines, one-off commands

Option 2: Global Installation (npm)

# Install globally
npm install -g n8n-cli

# Verify installation
n8n --version
n8n --help

Option 3: Global Installation (yarn)

# Install globally with yarn
yarn global add n8n-cli

# Verify installation
n8n --version

Option 4: Global Installation (pnpm)

# Install globally with pnpm
pnpm add -g n8n-cli

# Verify installation
n8n --version

Option 5: Project-Local Installation

# Add to project dependencies
npm install --save-dev n8n-cli

# Run via npx in project
npx n8n --help

# Or add to package.json scripts
# "scripts": { "n8n": "n8n-cli" }

Verify Installation

# Check version
n8n --version
# Output: n8n-cli/x.x.x

# Check available commands
n8n --help

# Test offline functionality (no API needed)
n8n nodes search "http"

# Test connection (requires configuration)
n8n health

Quick Start

For AI Agents

The recommended workflow for AI agents generating n8n workflows:

# 1. Search for available nodes (offline, no API needed)
n8n nodes search "slack" --json

# 2. Get node schema with minimal tokens (~200 tokens)
n8n nodes show n8n-nodes-base.slack --detail minimal --json

# 3. Get full schema when needed (~3-8K tokens)
n8n nodes show n8n-nodes-base.slack --detail full --json

# 4. Validate generated workflow (returns structured errors)
n8n workflows validate workflow.json --json

# 5. Auto-fix common issues
n8n workflows autofix workflow.json --apply --save fixed.json

# 6. Deploy to n8n instance (requires API configuration)
export N8N_HOST="https://your-n8n.com"
export N8N_API_KEY="your-api-key"
n8n workflows import workflow.json --json

Example JSON Response (Validation Error):

{
  "valid": false,
  "errors": [{
    "code": "EXPRESSION_MISSING_PREFIX",
    "nodeName": "HTTP Request",
    "path": "nodes[0].parameters.url",
    "context": {
      "value": "{{ $json.endpoint }}",
      "expected": "={{ $json.endpoint }}"
    },
    "hint": "Add '=' prefix to expression",
    "autoFixable": true
  }],
  "warnings": [],
  "stats": { "nodeCount": 5, "connectionCount": 4 }
}

For Humans

Common operations for human users:

# Check connection to n8n instance
n8n health

# List all workflows
n8n workflows list

# List active workflows only
n8n workflows list --active

# Export a workflow to file
n8n workflows export abc123 -o backup.json

# Validate a workflow file
n8n workflows validate workflow.json

# Validate and auto-fix issues
n8n workflows validate workflow.json --fix --save fixed.json

# Deploy a template from n8n.io in one command
n8n workflows deploy-template 3121 --name "My Chatbot"

# Search for nodes
n8n nodes search "google sheets"

# Get node documentation
n8n nodes show googleSheets --mode docs

💡 Quick Tip: Offline vs Online Commands
These commands work offline (no n8n instance needed): | Command | Description | |---------|-------------| | nodes search/show/list | Search 800+ bundled nodes | | workflows validate | Validate workflow JSON locally | | workflows autofix | Fix common issues automatically | | templates search --by-nodes/--by-task | Search bundled templates |
Everything else requires N8N_HOST and N8N_API_KEY configuration.

First 5 Minutes Guide

Step 1: Install the CLI

npm install -g n8n-cli

Step 2: Configure Connection (for API commands)

# Option A: Interactive setup
n8n auth login --interactive

# Option B: Environment variables
export N8N_HOST="https://your-n8n-instance.com"
export N8N_API_KEY="your-api-key-from-n8n-settings"

# Option C: Configuration file
echo 'N8N_HOST=https://your-n8n.com
N8N_API_KEY=your-api-key' > ~/.n8nrc

Step 3: Test the Connection

n8n health
# ✓ Connected to https://your-n8n.com
# ✓ API version: 1.0
# ✓ Latency: 45ms

Step 4: Explore Available Nodes (Offline)

# Search nodes by keyword
n8n nodes search "slack"

# List by category
n8n nodes list --by-category

# Get node schema
n8n nodes show slack --schema

Step 5: Validate and Deploy a Workflow

# Validate locally first
n8n workflows validate my-workflow.json

# Deploy if valid
n8n workflows import my-workflow.json --activate

⚠️ Warning: API commands (workflows list, credentials, executions, etc.) require N8N_HOST and N8N_API_KEY to be configured. Offline commands (nodes, validate, autofix) work without any configuration.

Quick Reference

Organized command reference for experienced users. For detailed documentation, see Commands.

Workflow Operations

# List & Get
n8n workflows list                          # List all (limit 20)
n8n workflows list -a -l 50                 # Active only, limit 50
n8n workflows list -t production,api        # Filter by tags
n8n workflows get abc123                    # Get by ID
n8n workflows get abc123 --json             # JSON output for scripting

# Export & Import
n8n workflows export abc123 -o backup.json  # Export to file
n8n workflows import workflow.json          # Import (inactive)
n8n workflows import workflow.json --activate  # Import and activate

# Validate & Fix
n8n workflows validate workflow.json        # Basic validation
n8n workflows validate abc123               # Validate by ID (API)
n8n workflows validate wf.json -P strict    # Strict profile
n8n workflows validate wf.json -P ai-friendly -M full  # AI workflow validation
n8n workflows validate wf.json --fix --save fixed.json  # Auto-fix issues
n8n workflows autofix wf.json --apply       # Full autofix with version upgrades

# Deploy Templates
n8n workflows deploy-template 3121          # Deploy template by ID
n8n workflows deploy-template 3121 -n "My Bot"  # Custom name
n8n workflows deploy-template 3121 --dry-run    # Preview without creating

Node Operations (Offline)

# Search & Discover
n8n nodes search "slack"                    # Basic search
n8n nodes search "http request" --mode AND  # All terms must match
n8n nodes search "slak" --mode FUZZY        # Typo-tolerant search
n8n nodes list --by-category                # Browse by category

# Get Node Info
n8n nodes show slack                        # Standard info (~1-2K tokens)
n8n nodes show slack --detail minimal       # Quick lookup (~200 tokens)
n8n nodes show slack --detail full          # Full schema (~3-8K tokens)
n8n nodes show slack --mode docs            # Human-readable documentation
n8n nodes show httpRequest --mode versions  # Version history

# Validate Nodes in Workflow
n8n nodes validate workflow.json            # Check node configurations
n8n nodes breaking-changes workflow.json    # Find outdated nodes

Credentials

n8n credentials list                        # List all credentials
n8n credentials types                       # Available credential types
n8n credentials schema githubApi            # Get type schema
n8n credentials create -t githubApi -n "GitHub" -d @creds.json  # Create from file
n8n credentials delete abc123 --force       # Delete without confirmation

Executions

n8n executions list                         # Recent executions
n8n executions list -w abc123               # Filter by workflow
n8n executions list --status error          # Failed only
n8n executions get exec123                  # Quick preview
n8n executions get exec123 --mode full      # Complete data (may be large)
n8n executions retry exec123                # Retry with same workflow version
n8n executions retry exec123 --load-latest  # Retry with current workflow

Templates (Offline Search)

n8n templates search "chatbot"              # Keyword search (API)
n8n templates search --by-nodes openAi,slack    # Local: by nodes used
n8n templates search --by-task ai_automation   # Local: by purpose
n8n templates get 3121                      # Template details
n8n templates list-tasks                    # All task categories

Admin & Config

n8n auth login --interactive                # Interactive setup
n8n auth status                             # Check current auth
n8n health                                  # Test connection
n8n audit --categories credentials,nodes    # Security audit
n8n config show                             # Current configuration

Command Patterns

| Pattern | Example | Description | |---------|---------|-------------| | List | n8n <resource> list [--filter] [--limit n] | List resources with optional filters | | Get | n8n <resource> get <id> [--json] | Get single resource by ID | | Create | n8n <resource> create [--data @file.json] | Create from data | | Delete | n8n <resource> delete <id> [--force] | Delete with optional confirmation skip | | Validate | n8n workflows validate <file> [--profile] | Validate with optional profile |

Console Output Examples

Validation Error (Terminal):

$ n8n workflows validate workflow.json
✗ Validation failed (2 errors)

❌ HTTP Request (nodes[0])
   EXPRESSION_MISSING_PREFIX
   Value: {{ $json.endpoint }}
   → Add '=' prefix: ={{ $json.endpoint }}
   💡 Auto-fixable with --fix

❌ Switch (nodes[2])
   OUTDATED_NODE_VERSION
   Current: v2, Latest: v3
   → Run: n8n workflows autofix workflow.json --upgrade-versions

Same Errors (JSON):

{
  "valid": false,
  "errors": [
    {"code": "EXPRESSION_MISSING_PREFIX", "nodeName": "HTTP Request", "autoFixable": true},
    {"code": "OUTDATED_NODE_VERSION", "nodeName": "Switch", "autoFixable": true}
  ]
}

Configuration

The CLI supports multiple configuration methods with the following priority order (highest to lowest):

Command-line arguments — --host, --api-key, --profile
Environment variables — N8N_HOST, N8N_API_KEY
Configuration files — .n8nrc, .n8nrc.json, etc.

Environment Variables

| Variable | Required | Default | Description | |----------|:--------:|---------|-------------| | N8N_HOST | Yes* | — | n8n instance URL (e.g., https://n8n.example.com) | | N8N_URL | Yes* | — | Alternative to N8N_HOST (same behavior) | | N8N_API_KEY | Yes* | — | API key from n8n Settings → API | | N8N_PROFILE | No | default | Configuration profile to use | | N8N_TIMEOUT | No | 30000 | API request timeout in milliseconds | | N8N_DB_PATH | No | (bundled) | Custom path to nodes SQLite database | | N8N_DEBUG | No | false | Enable debug logging (true/false) | | DEBUG | No | — | Set to n8n-cli for debug output | | N8N_STRICT_PERMISSIONS | No | false | Refuse config files with insecure permissions | | NO_COLOR | No | — | Disable colored output (any value) |

* Required for API commands only. Not required for offline commands (nodes, validate, autofix).

Example Usage:

# Inline environment variables
N8N_HOST="https://n8n.example.com" N8N_API_KEY="xxx" n8n workflows list

# Export for session
export N8N_HOST="https://n8n.example.com"
export N8N_API_KEY="your-api-key"
n8n workflows list

# Debug mode
N8N_DEBUG=true n8n workflows validate workflow.json

# Custom timeout (60 seconds)
N8N_TIMEOUT=60000 n8n workflows import large-workflow.json

Configuration Files

The CLI searches for configuration files in these locations (in priority order):

| Priority | Location | Format | Description | |:--------:|----------|--------|-------------| | 1 | .n8nrc | INI-style | Current directory | | 2 | .n8nrc.json | JSON | Current directory | | 3 | ~/.n8nrc | INI-style | Home directory | | 4 | ~/.n8nrc.json | JSON | Home directory | | 5 | ~/.config/n8n/config.json | JSON | XDG config directory |

INI-Style Format (.n8nrc):

# Simple key=value format
N8N_HOST=https://n8n.example.com
N8N_API_KEY=your-api-key
N8N_TIMEOUT=30000

JSON Format (.n8nrc.json):

{
  "host": "https://n8n.example.com",
  "apiKey": "your-api-key",
  "timeout": 30000
}

Configuration Profiles

For multiple environments (production, staging, development), use profiles:

{
  "default": "prod",
  "profiles": {
    "prod": {
      "host": "https://n8n.example.com",
      "apiKey": "prod-api-key-xxx"
    },
    "staging": {
      "host": "https://staging.n8n.example.com",
      "apiKey": "staging-api-key-xxx"
    },
    "dev": {
      "host": "http://localhost:5678",
      "apiKey": "dev-api-key-xxx"
    }
  }
}

Using Profiles:

# Command-line flag
n8n workflows list --profile dev

# Environment variable
N8N_PROFILE=staging n8n workflows list

# Default profile is used when not specified
n8n workflows list  # Uses "prod" profile (set as default)

Security Best Practices

| Practice | Recommendation | Example | |----------|----------------|---------| | File Permissions | Set 600 on config files | chmod 600 ~/.n8nrc | | API Key Storage | Use environment variables in CI/CD | ${{ secrets.N8N_API_KEY }} | | No Hardcoding | Never commit API keys to git | Add .n8nrc to .gitignore | | Credential Files | Use @file.json syntax | --data @secrets.json | | Strict Mode | Enable permission checking | N8N_STRICT_PERMISSIONS=true |

# Secure configuration file setup
echo 'N8N_HOST=https://n8n.example.com
N8N_API_KEY=your-api-key' > ~/.n8nrc
chmod 600 ~/.n8nrc
export N8N_STRICT_PERMISSIONS=true
n8n workflows list

💡 Tip: For first-time setup, use n8n auth login --interactive for guided configuration with connection testing.

Quick Command Reference

Command Groups Overview

| Command Group | Subcommands | Description | API Required | |---------------|-------------|-------------|:------------:| | auth | login, status, logout | Manage CLI authentication | ✗ (config only) | | health | — | Check n8n instance connectivity | ✓ | | nodes | list, show, get, search, categories, validate, breaking-changes | Search and inspect 800+ bundled nodes | ✗ (offline) | | workflows | list, get, validate, create, import, export, update, autofix, diff, versions, deploy-template, activate, deactivate, delete, trigger, tags | Full workflow lifecycle management | Mixed | | executions | list, get, retry, delete | View and manage workflow executions | ✓ | | credentials | list, create, delete, schema, types, show-type | Manage n8n credentials | Mixed | | variables | list, create, update, delete | Manage environment variables (Enterprise) | ✓ | | tags | list, get, create, update, delete | Organize workflows with tags | ✓ | | templates | search, get, list-tasks | Search and deploy n8n.io templates | Mixed | | audit | — | Generate security audit reports | ✓ | | config | show | View CLI configuration | ✗ | | completion | <shell> | Generate shell completions | ✗ | | validate | — | Legacy workflow validation | ✗ (offline) |

Offline vs API Commands

| Offline (No API Needed) | Requires n8n API | |-------------------------|------------------| | nodes * (all subcommands) | workflows list/get/create/import/update/delete/activate/deactivate/trigger/tags | | workflows validate | executions * (all subcommands) | | workflows autofix | credentials list/create/delete/schema | | workflows versions | variables * (all subcommands) | | credentials types | tags * (all subcommands) | | templates search --local | — | | templates search --by-nodes | health | | templates search --by-task | health | | templates list-tasks | — | | validate (legacy) | — | | config show | — | | completion | — |

Global Options

These options are available on all commands:

| Option | Short | Description | |--------|-------|-------------| | --version | -V | Output version number and exit | | --verbose | -v | Enable verbose/debug output | | --quiet | -q | Suppress non-essential output | | --no-color | — | Disable colored output | | --profile <name> | — | Use specific configuration profile | | --help | -h | Display help for command |

Common Command Options:

| Option | Description | Available On | |--------|-------------|--------------| | --json | Output as JSON (machine-readable) | Most commands | | --save <path> | Save output to file | Most commands | | --force, --yes | Skip confirmation prompts | Destructive commands | | --no-backup | Skip automatic backup | Update/delete commands | | --limit <n> | Limit number of results | List commands | | --cursor <cursor> | Pagination cursor for next page | List commands |

Commands

`workflows`

Manage n8n workflows — the complete lifecycle from creation to deployment, validation, versioning, and more.

The workflows command group provides 16 subcommands covering:

CRUD Operations: create, import, get, export, update, delete
Validation & Fixing: validate, autofix
Version Management: versions (history, rollback, compare)
Advanced Operations: diff (surgical updates), deploy-template
State Management: activate, deactivate, trigger
Organization: tags

Command Overview

| Command | Description | API Required | |---------|-------------|:------------:| | list | List all workflows | ✓ | | get | Get workflow by ID | ✓ | | validate | Validate workflow structure | ✗ | | create | Create new workflow | ✓ | | import | Import from JSON file | ✓ | | export | Export to JSON file | ✓ | | update | Update existing workflow | ✓ | | autofix | Auto-fix validation issues | ✗ | | diff | Apply incremental changes | ✓ | | versions | Manage version history | ✗ | | deploy-template | Deploy n8n.io template | ✓ | | activate | Activate workflow(s) | ✓ | | deactivate | Deactivate workflow(s) | ✓ | | delete | Delete workflow(s) | ✓ | | trigger | Trigger via webhook | ✓ | | tags | Manage workflow tags | ✓ |

`workflows list`

List all workflows from your n8n instance with filtering and pagination support.

Usage:

n8n workflows list [options]

Options:

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --active | -a | Filter active workflows only | — | | --tags <tags> | -t | Filter by tags (comma-separated) | — | | --limit <n> | -l | Limit results (0 = all) | 10 | | --cursor <cursor> | — | Pagination cursor for next page | — | | --save <path> | -s | Save output to JSON file | — | | --json | — | Output as JSON | — |

Examples:

# List all workflows (default limit: 10)
n8n workflows list

# List all active workflows
n8n workflows list --active

# List workflows with specific tags
n8n workflows list --tags production,api

# List all workflows (no limit)
n8n workflows list --limit 0

# Get JSON output for scripting
n8n workflows list --json

# Save to file
n8n workflows list --save workflows.json

# Paginate through results
n8n workflows list --cursor "eyJsaW1pdCI6MTAsIm9mZnNldCI6MTB9"

jq Recipes:

# Extract workflow IDs and names
n8n workflows list --json | jq '.data[] | {id, name}'

# Count active workflows
n8n workflows list --active --limit 0 --json | jq '.data | length'

# Get workflows updated in last 7 days
n8n workflows list --json | jq '.data[] | select(.updatedAt > (now - 604800 | todate))'

`workflows get`

Get a single workflow by ID with configurable output detail.

Usage:

n8n workflows get <id> [options]

Options:

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --mode <mode> | -m | Output mode: full, details, structure, minimal | full | | --save <path> | -s | Save output to JSON file | — | | --json | — | Output as JSON | — |

Output Modes:

| Mode | Contents | Use Case | |------|----------|----------| | full | Complete workflow with all fields | Export, backup | | details | Metadata + node list (no parameters) | Quick overview | | structure | Nodes and connections only | Structure analysis | | minimal | ID, name, active status only | Status checks |

Examples:

# Get full workflow
n8n workflows get abc123

# Get minimal info
n8n workflows get abc123 --mode minimal

# Export to file
n8n workflows get abc123 --save workflow-backup.json

# JSON for scripting
n8n workflows get abc123 --json | jq '.nodes | length'

`workflows export`

Export a workflow to JSON file.

Usage:

n8n workflows export <id> [options]

Options:

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --output <path> | -o | Output file path (stdout if not specified) | — | | --full | — | Include all fields (don't strip server-generated) | — | | --json | — | Output as JSON | — |

Examples:

# Export to stdout
n8n workflows export abc123

# Export to file
n8n workflows export abc123 -o backup.json

# Export with all server fields
n8n workflows export abc123 --full -o complete-backup.json

# Pipe to another command
n8n workflows export abc123 | jq '.nodes | length'

`workflows validate`

Validate a workflow JSON file or workflow by ID with comprehensive schema-aware validation. This is the primary validation command with extensive options for different use cases.

Usage:

n8n workflows validate [idOrFile] [options]

Options:

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --file <path> | -f | Path to workflow JSON file | — | | --validation-profile <profile> | -P | Profile: minimal, runtime, ai-friendly, strict | runtime | | --validation-mode <mode> | -M | Mode: minimal, operation, full | operation | | --repair | — | Attempt to repair malformed JSON | — | | --fix | — | Auto-fix known issues | — | | --check-upgrades | — | Check for node version upgrades | — | | --upgrade-severity <level> | — | Minimum severity: LOW, MEDIUM, HIGH | — | | --check-versions | — | Check for outdated typeVersions | — | | --version-severity <level> | — | Version severity: info, warning, error | warning | | --skip-community-nodes | — | Skip version checks for community nodes | — | | --validate-expressions | — | Enable expression format validation | true | | --no-validate-expressions | — | Skip expression format validation | — | | --save <path> | -s | Save fixed workflow to file | — | | --json | — | Output as JSON | — |

Validation Profiles

| Profile | Errors Kept | Warnings Kept | Use Case | |---------|-------------|---------------|----------| | minimal | Missing required only | Security, deprecated | Fast structure check | | runtime | Critical runtime errors | Security, deprecated | Default for CLI | | ai-friendly | All errors | + Best practice, missing common | AI agent workflows | | strict | All errors | All + enforced error handling | Production validation |

Validation Modes

| Mode | Scope | Description | |------|-------|-------------| | minimal | Required + visible | Only required properties currently visible | | operation | Operation-specific | Properties relevant to current resource/operation | | full | All properties | All properties regardless of visibility |

Version Upgrade Checking

Use --check-upgrades to analyze nodes in the workflow for available version upgrades:

# Check for upgrade recommendations
n8n workflows validate workflow.json --check-upgrades

# Get JSON output with upgrade analysis
n8n workflows validate workflow.json --check-upgrades --json

# Only show high severity breaking changes
n8n workflows validate workflow.json --check-upgrades --upgrade-severity HIGH

Node Version Checking

Use --check-versions to check for outdated node typeVersion values:

# Check for outdated node versions
n8n workflows validate workflow.json --check-versions

# Set severity level for version issues
n8n workflows validate workflow.json --check-versions --version-severity error

# Skip community nodes (only check n8n-nodes-base)
n8n workflows validate workflow.json --check-versions --skip-community-nodes

JSON Output Examples

Example: Expression Error

{
  "valid": false,
  "errors": [{
    "code": "EXPRESSION_MISSING_PREFIX",
    "nodeName": "HTTP Request",
    "path": "nodes[0].parameters.url",
    "context": {
      "value": "{{ $json.endpoint }}",
      "expected": "={{ $json.endpoint }}"
    },
    "hint": "Add '=' prefix: ={{ $json.endpoint }}",
    "autoFixable": true
  }]
}

Example: Structural Error

{
  "valid": false,
  "errors": [{
    "code": "N8N_PARAMETER_VALIDATION_ERROR",
    "nodeName": "Switch",
    "path": "nodes[2].parameters",
    "schemaDelta": {
      "missing": ["options"],
      "extra": ["fallbackOutput"]
    },
    "correctUsage": {
      "conditions": {
        "options": {
          "caseSensitive": true
        }
      }
    },
    "hint": "Remove 'fallbackOutput' and add 'options' property"
  }]
}

Example: Node Type Suggestion

{
  "valid": false,
  "issues": [{
    "code": "INVALID_NODE_TYPE_FORMAT",
    "message": "Node has invalid type \"httprequest\"",
    "nodeName": "HTTP Request",
    "path": "nodes[0].type",
    "suggestions": [
      {
        "value": "n8n-nodes-base.httpRequest",
        "confidence": 0.95,
        "reason": "Missing package prefix",
        "autoFixable": true
      }
    ],
    "hint": "Did you mean: n8n-nodes-base.httpRequest? (95% match)"
  }]
}

Use n8n workflows autofix with --fix-types node-type-correction to automatically fix high-confidence matches (>90%):

n8n workflows autofix workflow.json --apply --fix-types node-type-correction

Expression Format Validation

The CLI validates that n8n expressions have the required = prefix. Expressions like {{ $json.field }} are detected as errors because they won't be evaluated without the prefix.

# Validate with expression checking (default)
n8n workflows validate workflow.json

# Skip expression validation (for templates with intentional placeholders)
n8n workflows validate workflow.json --no-validate-expressions

Example Error Output (Expression):

{
  "valid": false,
  "errors": [{
    "code": "EXPRESSION_MISSING_PREFIX",
    "nodeName": "HTTP Request",
    "path": "nodes[0].parameters.url",
    "context": {
      "value": "{{ $json.endpoint }}",
      "expected": "={{ $json.endpoint }}"
    },
    "hint": "Add '=' prefix to expression",
    "autoFixable": true
  }]
}

Node Type Suggestions

When the CLI detects an unknown or misspelled node type, it provides intelligent suggestions using fuzzy matching:

{
  "valid": false,
  "issues": [{
    "code": "INVALID_NODE_TYPE_FORMAT",
    "message": "Node has invalid type \"httprequest\"",
    "nodeName": "HTTP Request",
    "path": "nodes[0].type",
    "suggestions": [
      {
        "value": "n8n-nodes-base.httpRequest",
        "confidence": 0.95,
        "reason": "Missing package prefix",
        "autoFixable": true
      }
    ],
    "hint": "Did you mean: n8n-nodes-base.httpRequest? (95% match)"
  }]
}

AI Node Validation

The CLI includes specialized validation for AI Agent workflows, catching common misconfigurations:

| AI Node Type | Validations | |--------------|-------------| | AI Agent | LLM connection required, fallback model config, output parser, streaming mode, memory limits, tool connections, maxIterations, prompt/systemMessage | | Chat Trigger | Streaming mode requires AI Agent target, agent can't have main outputs in streaming | | Basic LLM Chain | Single LLM required, no fallback support, no tools allowed | | AI Tools (12 types) | HTTP Request, Code, Vector Store, Workflow, MCP Client, Calculator, Think, SerpApi, Wikipedia, SearXNG, WolframAlpha |

AI Validation Error Codes:

| Code | Description | |------|-------------| | MISSING_LANGUAGE_MODEL | AI Agent/Chain requires ai_languageModel connection | | TOO_MANY_LANGUAGE_MODELS | Maximum 2 LLMs allowed (for fallback) | | FALLBACK_MISSING_SECOND_MODEL | needsFallback=true but only 1 LLM connected | | MISSING_OUTPUT_PARSER | hasOutputParser=true but no parser connected | | STREAMING_WITH_MAIN_OUTPUT | Agent in streaming mode can't have main outputs | | STREAMING_WRONG_TARGET | Streaming mode only works with AI Agent | | MULTIPLE_MEMORY_CONNECTIONS | Only 1 memory connection allowed | | MISSING_TOOL_DESCRIPTION | AI tool requires toolDescription | | MISSING_PROMPT_TEXT | promptType="define" but text is empty |

`workflows create`

Create a new workflow from a JSON file.

Usage:

n8n workflows create [options]

Options:

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --file <path> | -f | Path to workflow JSON file | — | | --name <name> | -n | Override workflow name | — | | --dry-run | — | Preview without creating | — | | --skip-validation | — | Skip pre-API validation (not recommended) | — | | --json | — | Output as JSON | — |

Examples:

# Create workflow from file
n8n workflows create -f workflow.json

# Create with custom name
n8n workflows create -f workflow.json --name "My Custom Workflow"

# Preview without creating
n8n workflows create -f workflow.json --dry-run

# JSON output for scripting
n8n workflows create -f workflow.json --json

`workflows import`

Import workflow from JSON file. This is an alias for create with slightly different syntax.

Usage:

n8n workflows import <file> [options]

Options:

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --name <name> | -n | Override workflow name | — | | --dry-run | — | Preview without creating | — | | --activate | — | Activate immediately after import | — | | --skip-validation | — | Skip pre-API validation (not recommended) | — | | --json | — | Output as JSON | — |

Examples:

# Import workflow
n8n workflows import workflow.json

# Import with custom name
n8n workflows import workflow.json --name "Production Workflow"

# Import and activate immediately
n8n workflows import workflow.json --activate

# Preview import
n8n workflows import workflow.json --dry-run

`workflows update`

Update an existing workflow with a new version.

Usage:

n8n workflows update <id> [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | --file <path> | Path to workflow JSON file | — | | --operations <json> | Comma-separated operation IDs | — | | --name <name> | Update workflow name | — | | --activate | Activate the workflow | — | | --deactivate | Deactivate the workflow | — | | --skip-validation | Skip pre-API validation | — | | --force, --yes | Skip confirmation prompts | — | | --no-backup | Skip creating backup | — | | --json | Output as JSON | — |

Examples:

# Update workflow from file
n8n workflows update abc123 -f updated-workflow.json

# Update workflow name only
n8n workflows update abc123 --name "Renamed Workflow"

# Activate/deactivate workflow
n8n workflows update abc123 --activate
n8n workflows update abc123 --deactivate

# Update with force (no confirmation)
n8n workflows update abc123 -f workflow.json --force

`workflows activate` / `deactivate`

Bulk activate or deactivate workflows.

Usage:

n8n workflows activate [options]
n8n workflows deactivate [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | --ids <ids> | Comma-separated workflow IDs | — | | --all | Apply to all workflows | — | | --force, --yes | Skip confirmation prompt | — | | --json | Output as JSON | — |

Examples:

# Activate specific workflows
n8n workflows activate --ids abc123,def456,ghi789

# Deactivate all workflows (with confirmation)
n8n workflows deactivate --all

# Force deactivate without confirmation (still creates backup)
n8n workflows deactivate --all --force

⚠️ Warning: --all combined with --force will delete all workflows. Use with extreme caution. Backups are saved to ~/.n8n-cli/backups/ unless --no-backup is specified.

`workflows trigger`

Trigger a workflow via its webhook URL.

Usage:

n8n workflows trigger <webhookUrl> [options]

Options:

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --data <json> | -d | Request body (JSON string or @file.json) | {} | | --method <method> | -m | HTTP method: GET, POST, PUT, DELETE | POST | | --json | — | Output as JSON | — |

Examples:

# Trigger with POST (default)
n8n workflows trigger https://n8n.example.com/webhook/abc123

# Trigger with data
n8n workflows trigger https://n8n.example.com/webhook/abc123 \
  --data '{"name": "John", "email": "[email protected]"}'

# Trigger with data from file
n8n workflows trigger https://n8n.example.com/webhook/abc123 \
  --data @payload.json

# Trigger with GET method
n8n workflows trigger https://n8n.example.com/webhook/abc123 --method GET

`workflows tags`

Get or set tags for a workflow.

Usage:

n8n workflows tags <id> [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | --set <tagIds> | Set tags (comma-separated tag IDs) | — | | --force, --yes | Skip confirmation prompt | — | | --json | Output as JSON | — |

Examples:

# Get current tags
n8n workflows tags abc123

# Set tags (replaces existing)
n8n workflows tags abc123 --set tag1,tag2,tag3

# Force set without confirmation
n8n workflows tags abc123 --set tag1,tag2 --force

`workflows autofix`

Advanced autofix engine with confidence-based filtering for workflow validation issues.

Usage:

n8n workflows autofix <idOrFile> [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | --preview | Preview fixes without applying | (default) | | --apply | Apply fixes (to file or n8n server) | — | | --confidence <level> | Minimum confidence: high, medium, low | medium | | --fix-types <types> | Comma-separated fix types to apply | all | | --upgrade-versions | Apply version migration fixes | — | | --target-version <version> | Target version for upgrades | Latest | | --max-fixes <n> | Maximum number of fixes | 50 | | --save <path> | Save fixed workflow locally | — | | --force, --yes | Skip confirmation prompts | — | | --no-backup | Skip backup before changes | — | | --no-guidance | Suppress post-update guidance | — | | --json | Output as JSON | — |

Fix Types and Confidence Levels

| Fix Type | Confidence | Description | |----------|------------|-------------| | expression-format | HIGH | Add missing = prefix to {{ }} expressions | | node-type-correction | HIGH | Fix typos in node types (when >90% match) | | webhook-missing-path | HIGH | Generate UUID paths for webhook nodes | | switch-options | HIGH | Fix Switch/If node options and conditions | | typeversion-correction | MEDIUM | Fix version exceeding max supported | | error-output-config | MEDIUM | Remove invalid onError settings | | typeversion-upgrade | MEDIUM | Suggest version upgrades | | version-migration | LOW | Breaking change migration hints |

Post-Update Guidance

After applying fixes, the autofix command displays actionable migration guidance for each affected node:

Confidence Scores — Each upgrade is rated HIGH, MEDIUM, or LOW based on remaining manual work required
Required Actions — Step-by-step list of manual tasks needed after the automated fix
Behavior Changes — Documents how node behavior changed between versions
Estimated Time — Expected time to complete manual verification

The guidance is included in JSON output (--json) as a postUpdateGuidance array containing structured migration instructions for each node. Use --no-guidance to suppress the guidance display in the terminal output.

Example Guidance Output:

╔════════════════════════════════════════════════════════╗
║ ℹ Post-Update Guidance                                               ║
╚══════════════════════════════════════════════════════════╝
║ Node: My Switch (abc12345...)                                        ║
║ Type: n8n-nodes-base.switch                                          ║
║ Version: v2 → v3                                                     ║
╟──────────────────────────────────────────────────────────────────────╢
║ Status: ◐ Partial (Manual review required)                          ║
║ Confidence: MEDIUM                                                   ║
║ Est. Time: 2-5 minutes                                               ║
╟──────────────────────────────────────────────────────────────────────╢
║ ✓ Automated Changes (2):                                             ║
║   • Migrated 'rules' to 'conditions.options'                         ║
║   • Updated rule structure to v3 format                              ║
╟──────────────────────────────────────────────────────────────────────╢
║ ⚠ Manual Actions Required (1):                                       ║
║   • Review rule conditions and ensure type matching is correct       ║
╟──────────────────────────────────────────────────────────────────────╢
║ ℹ Behavior Changes (1):                                              ║
║   • Rule evaluation now strictly enforces data types                 ║
║     → String "123" will no longer match number 123                   ║
╚══════════════════════════════════════════════════════════════════════╝

JSON Output Structure:

{
  "success": true,
  "fixesApplied": 12,
  "postUpdateGuidance": [
    {
      "nodeId": "abc12345...",
      "nodeName": "My Switch",
      "nodeType": "n8n-nodes-base.switch",
      "fromVersion": 2,
      "toVersion": 3,
      "status": "partial",
      "confidence": "MEDIUM",
      "estimatedTime": "2-5 minutes",
      "automatedChanges": [
        "Migrated 'rules' to 'conditions.options'",
        "Updated rule structure to v3 format"
      ],
      "manualActions": [
        "Review rule conditions and ensure type matching is correct"
      ],
      "behaviorChanges": [
        {
          "change": "Rule evaluation now strictly enforces data types",
          "example": "String \"123\" will no longer match number 123"
        }
      ]
    }
  ]
}

Examples:

# Preview all fixes (default mode)
n8n workflows autofix abc123

# Preview from local file
n8n workflows autofix workflow.json

# Apply only high-confidence fixes
n8n workflows autofix abc123 --apply --confidence high

# Filter to specific fix types
n8n workflows autofix abc123 --fix-types expression-format,node-type-correction

# Apply version migration fixes
n8n workflows autofix workflow.json --upgrade-versions --apply

# Save fixed workflow locally
n8n workflows autofix workflow.json --apply --save fixed.json

# Apply with JSON output for scripting
n8n workflows autofix abc123 --apply --force --json

# Apply fixes without guidance display
n8n workflows autofix abc123 --apply --no-guidance

`workflows versions`

Manage workflow version history, rollback, and cleanup. Versions are created automatically when you update or autofix workflows, stored locally in ~/.n8n-cli/data.db.

Usage:

n8n workflows versions [id] [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | --limit <n> | Limit version history results | 10 | | --get <version-id> | Get specific version details | — | | --rollback | Rollback to previous version | — | | --to-version <id> | Specific version ID for rollback | — | | --skip-validation | Skip validation before rollback | — | | --compare <v1,v2> | Compare two versions (comma-separated) | — | | --delete <version-id> | Delete specific version | — | | --delete-all | Delete all versions for workflow | — | | --prune | Prune old versions | — | | --keep <n> | Keep N most recent (with --prune) | 5 | | --stats | Show storage statistics (no ID required) | — | | --truncate-all | Delete ALL versions for ALL workflows | — | | --force, --yes | Skip confirmation prompts | — | | --no-backup | Skip backup before rollback | — | | --save <path> | Save version snapshot to JSON file | — | | --json | Output as JSON | — |

Note: Auto-pruning keeps max 10 versions per workflow automatically.

Examples:

# List version history
n8n workflows versions abc123

# View storage statistics (global)
n8n workflows versions --stats

# Get specific version details
n8n workflows versions abc123 --get 42

# Save version to file
n8n workflows versions abc123 --get 42 --save version.json

# Rollback to previous version
n8n workflows versions abc123 --rollback

# Rollback to specific version
n8n workflows versions abc123 --rollback --to-version 42

# Compare two versions
n8n workflows versions abc123 --compare 41,42

# Prune old versions (keep 5 most recent)
n8n workflows versions abc123 --prune --keep 5

# Delete specific version
n8n workflows versions abc123 --delete 42

# Delete all versions for workflow
n8n workflows versions abc123 --delete-all --force

`workflows diff`

Apply incremental diff operations to a workflow. Enables surgical modifications without full replacement.

Usage:

n8n workflows diff <id> [options]

Options:

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --operations <json> | -o | Diff operations (JSON string or @file.json) | — | | --file <path> | -f | Path to operations JSON file | — | | --dry-run | — | Validate without applying changes | false | | --continue-on-error | — | Apply valid operations, report failures | false | | --skip-validation | — | Skip pre-API validation | — | | --force, --yes | — | Skip confirmation prompts | — | | --no-backup | — | Skip backup before changes | — | | --save <path> | -s | Save result workflow to file | — | | --json | — | Output as JSON | — |

Supported Operations (17 types)

Node Operations:

addNode — Add a new node
removeNode — Remove node and its connections
updateNode — Update node parameters
moveNode — Change node position
enableNode — Enable a disabled node
disableNode — Disable node (keeps in workflow)

Connection Operations:

addConnection — Add connection between nodes
removeConnection — Remove a connection
rewireConnection — Change connection target
cleanStaleConnections — Remove orphaned connections
replaceConnections — Replace all connections

Metadata Operations:

updateSettings — Update workflow settings
updateName — Rename workflow
addTag — Add tag to workflow
removeTag — Remove tag from workflow

Activation Operations:

activateWorkflow — Activate workflow
deactivateWorkflow — Deactivate workflow

Smart Parameters for Conditional Nodes

For IF and Switch nodes, you can use semantic parameters instead of numeric indexes:

| Node Type | Smart Parameter | Alternative | Description | |-----------|----------------|-------------|-------------| | IF Node | branch: "true" | sourceIndex: 0 | Connection from "true" output | | IF Node | branch: "false" | sourceIndex: 1 | Connection from "false" output | | Switch Node | case: 0 | sourceIndex: 0 | First case output | | Switch Node | case: 1 | sourceIndex: 1 | Second case output | | Switch Node | case: 2 | sourceIndex: 2 | Third case output |

Example using smart parameters:

{
  "type": "addConnection",
  "source": "IF",
  "target": "Success Handler",
  "branch": "true"
}

Equivalent using sourceIndex:

{
  "type": "addConnection",
  "source": "IF",
  "target": "Success Handler",
  "sourceIndex": 0
}

Detailed Operation Examples

| Operation | JSON Syntax | Description | |-----------|-------------|-------------| | addNode | {"type":"addNode","node":{"name":"HTTP","type":"n8n-nodes-base.httpRequest","position":[400,300],"parameters":{"url":"https://api.example.com"}}} | Add new node with position and parameters | | removeNode | {"type":"removeNode","nodeName":"Unused Node"} | Remove node and all its connections | | updateNode | {"type":"updateNode","nodeName":"Slack","updates":{"parameters.channel":"#alerts","parameters.text":"New message"}} | Update node parameters using dot notation | | moveNode | {"type":"moveNode","nodeName":"HTTP","position":[500,400]} | Change node canvas position | | enableNode | {"type":"enableNode","nodeName":"Debug"} | Enable a disabled node | | disableNode | {"type":"disableNode","nodeName":"Debug"} | Disable node (keeps in workflow) | | addConnection | {"type":"addConnection","source":"IF","target":"Success","branch":"true"} | Add connection between nodes | | removeConnection | {"type":"removeConnection","source":"IF","target":"Success","sourceIndex":0} | Remove specific connection | | rewireConnection | {"type":"rewireConnection","source":"IF","oldTarget":"OldNode","newTarget":"NewNode","sourceIndex":0} | Change connection target | | cleanStaleConnections | {"type":"cleanStaleConnections"} | Remove all orphaned connections | | replaceConnections | {"type":"replaceConnections","nodeName":"HTTP","connections":{"main":[[{"node":"Slack","type":"main","index":0}]]}} | Replace all connections for a node | | updateSettings | {"type":"updateSettings","settings":{"executionOrder":"v1"}} | Update workflow settings | | updateName | {"type":"updateName","name":"New Workflow Name"} | Rename workflow | | addTag | {"type":"addTag","tagId":"BCM4YL05avZ5KuP2"} | Add tag to workflow | | removeTag | {"type":"removeTag","tagId":"BCM4YL05avZ5KuP2"} | Remove tag from workflow | | activateWorkflow | {"type":"activateWorkflow"} | Activate workflow | | deactivateWorkflow | {"type":"deactivateWorkflow"} | Deactivate workflow |

Example Operations JSON:

{
  "operations": [
    {
      "type": "addNode",
      "node": {
        "name": "HTTP Request",
        "type": "n8n-nodes-base.httpRequest",
        "position": [400, 300],
        "parameters": { "url": "https://api.example.com" }
      }
    },
    {
      "type": "updateNode",
      "nodeName": "Slack",
      "updates": { "parameters.channel": "#alerts", "parameters.text": "New message" }
    },
    {
      "type": "addConnection",
      "source": "IF",
      "target": "Success Handler",
      "branch": "true"
    },
    {
      "type": "removeNode",
      "nodeName": "Unused Node"
    }
  ]
}

Examples:

# Apply diff operations from JSON string
n8n workflows diff abc123 -o '{"operations":[{"type":"updateNode","nodeName":"Slack","updates":{"parameters.channel":"#alerts","parameters.text":"New message"}}]}'

# Apply diff operations from file
n8n workflows diff abc123 -f operations.json

# Dry-run to validate operations
n8n workflows diff abc123 -f operations.json --dry-run

# Apply with continue-on-error
n8n workflows diff abc123 -f operations.json --continue-on-error

# Save result without pushing to server
n8n workflows diff abc123 -f operations.json --save result.json

`workflows deploy-template`

Deploy a workflow template from n8n.io directly to your n8n instance.

Usage:

n8n workflows deploy-template <templateId> [options]

Options:

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --name <name> | -n | Custom workflow name | Template name | | --no-autofix | — | Skip auto-fix (expression format, etc.) | — | | --keep-credentials | — | Preserve credential references | — | | --dry-run | — | Preview without creating | — | | --save <path> | -s | Save locally instead of deploying | — | | --json | — | Output as JSON | — |

Features:

Fetches templates from n8n.io public API
Auto-fixes expression format issues ({{}} → ={{}})
Auto-fixes Switch v3+ rule conditions
Extracts and displays required credentials before stripping
Creates workflows as inactive (safe default)
Supports dry-run, save, JSON output modes

Examples:

# Deploy template (shows required credentials)
n8n workflows deploy-template 3121

# Deploy with custom name
n8n workflows deploy-template 3121 --name "My Custom Chatbot"

# Preview without deploying
n8n workflows deploy-template 3121 --dry-run

# Save locally instead of deploying
n8n workflows deploy-template 3121 --save chatbot-template.json

# Deploy without autofix
n8n workflows deploy-template 3121 --no-autofix

# Keep credential references (useful for debugging)
n8n workflows deploy-template 3121 --keep-credentials

Finding Templates:

Use templates search to discover templates before deploying:

# Search by keyword
n8n templates search "keyword"

# Search by nodes used
n8n templates search --by-nodes node1,node2

# Search by task category
n8n templates search --by-task ai_automation

# Get template details
n8n templates get 3121

`nodes`

Search, browse, and inspect n8n's 800+ bundled nodes entirely offline. All node metadata is stored in a local SQLite database — no API connection required.

Command Overview

| Command | Description | API Required | |---------|-------------|:------------:| | list | List all available nodes | ✗ | | search | Search nodes by keyword | ✗ | | show | Get detailed node information | ✗ | | get | Alias for show | ✗ | | categories | List node categories | ✗ | | validate | Validate node configuration | ✗ | | breaking-changes | Analyze version breaking changes | ✗ |

`nodes list`

List all available nodes with filtering and grouping options.

Usage:

n8n nodes list [options]

Options:

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --by-category | — | Group nodes by category | — | | --category <name> | -c | Filter by specific category | — | | --compact | — | Compact output (name only) | — | | --limit <n> | -l | Limit results | — | | --save <path> | -s | Save output to JSON file | — | | --json | — | Output as JSON | — |

Examples:

# List all nodes
n8n nodes list

# List all nodes in a category
n8n nodes list --category "Marketing & Content"

# Compact list (names only)
n8n nodes list --compact

# JSON output for scripting
n8n nodes list --json | jq '.nodes | length'

`nodes search`

Search nodes by keyword with multiple search modes and FTS5 full-text search support.

Usage:

n8n nodes search <query> [options]

Options:

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --mode <mode> | -m | Search mode: OR, AND, FUZZY | OR | | --category <name> | -c | Filter by category | — | | --limit <n> | -l | Limit results | 20 | | --save <path> | -s | Save output to file | — | | --json | — | Output as JSON | — |

Search Modes:

| Mode | Description | Use Case | |------|-------------|----------| | OR | Match any keyword | Broad search, discovering options | | AND | Match all keywords | Precise multi-term search | | FUZZY | Levenshtein distance matching | Typo-tolerant search |

FTS5 Full-Text Search

When an FTS5 index (nodes_fts table) exists in the bundled database, the CLI automatically uses BM25-ranked full-text search for faster, more relevant results:

| Feature | Description | |---------|-------------| | Auto-detection | FTS5 tables detected lazily on first search | | BM25 ranking | Results sorted by relevance score (term frequency × inverse document frequency) | | Phrase matching | Use quotes for exact phrases: "http request" | | Boolean operators | Support for AND, OR, NOT in queries | | Graceful fallback | Falls back to LIKE search on FTS5 syntax errors | | FUZZY mode exception | FUZZY mode always uses Levenshtein distance (no FTS5) |

FTS5 Examples:

# OR search with BM25 ranking (default)
n8n nodes search "slack message"

# AND search (all must match)
n8n nodes search "http request" --mode AND

# Phrase search (exact match)
n8n nodes search '"send email"'

# Fuzzy search (typo tolerance)
n8n nodes search "slak" --mode FUZZY

How FTS5 Improves Results:

| Without FTS5 (LIKE search) | With FTS5 (full-text search) | |---------------------------|------------------------------| | Sequential scan through all nodes | Indexed search (faster) | | No relevance ranking | Results ranked by relevance | | Results in alphabetical order | Best matches first | | Basic substring matching | Better handling of partial words |

Examples:

# Basic search (OR mode)
n8n nodes search "slack"

# Multi-word search (all must match)
n8n nodes search "http request" --mode AND

# Fuzzy search (typo tolerance)
n8n nodes search "slak" --mode FUZZY

# Search within category
n8n nodes search "google" --category "Marketing & Content"

# JSON output
n8n nodes search "email" --json

`nodes show`

Get detailed information about a specific node type with multiple output modes and version comparison capabilities.

Usage:

n8n nodes show <nodeType> [options]

Options:

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --detail <level> | -d | Detail level: minimal (~200 tokens), standard (~1-2K), full (~3-8K) | standard | | --mode <mode> | -m | Operation mode (see table below) | info | | --query <term> | — | Property search term (for search-properties mode) | — | | --from <version> | — | Source version (for compare, breaking, migrations) | — | | --to <version> | — | Target version (for compare, migrations) | Latest | | --max-results <n> | — | Max property search results | 20 | | --include-type-info | — | Include type structure metadata | — | | --include-examples | — | Include real-world configuration examples | — | | --resource <name> | -r | Filter by resource | — | | --operation <name> | -o | Filter by operation | — | | --version <n> | -v | Specific typeVersion | Latest | | --schema | — | Legacy: equivalent to --detail full | — | | --minimal | — | Legacy: equivalent to --detail minimal | — | | --examples | — | Legacy: equivalent to --include-examples | — | | --save <path> | -s | Save output to file | — | | --json | — | Output as JSON | — |

Detail Levels:

| Level | Token Count | Contents | Use Case | |-------|-------------|----------|----------| | minimal | ~200 tokens | Basic info + essential properties | Quick lookups, AI context optimization | | standard | ~1-2K tokens | Essential properties + operations | Default for most use cases | | full | ~3-8K tokens | Complete schema with all properties | Workflow generation, comprehensive reference |

Operation Modes:

| Mode | Description | Required Options | |------|-------------|------------------| | info | Node configuration schema (default) | — | | docs | Markdown documentation | — | | search-properties | Find properties by keyword | --query <term> | | versions | Version history with breaking changes | — | | compare | Property diff between versions | --from <version> | | breaking | Breaking changes between versions | --from <version> (optional) | | migrations | Auto-migratable changes | --from <version>, --to <version> (optional) |

**Examples:

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Table of Contents

Part 1: Getting Started

Part 2: Configuration

Part 3: Command Reference

Part 4: Advanced Usage

Part 5: Reference & Support

Why Agent-First?

The Agent Development Loop

Key Design Principles

Feature Overview

Target Audience

What Sets This CLI Apart

Installation

Requirements

Installation Methods

Option 1: Run Directly with npx (No Installation)

Option 2: Global Installation (npm)

Option 3: Global Installation (yarn)

Option 4: Global Installation (pnpm)

Option 5: Project-Local Installation

Verify Installation

Quick Start

For AI Agents

For Humans

First 5 Minutes Guide

Quick Reference

Workflow Operations

Node Operations (Offline)

Credentials

Executions

Templates (Offline Search)

Admin & Config

Command Patterns

Console Output Examples

Configuration

Environment Variables

Configuration Files

Configuration Profiles

Security Best Practices

Quick Command Reference

Command Groups Overview

Offline vs API Commands

Global Options

Commands

workflows

Command Overview

workflows list

workflows get

workflows export

workflows validate

Validation Profiles

Validation Modes

Version Upgrade Checking

Node Version Checking

JSON Output Examples

Expression Format Validation

Node Type Suggestions

AI Node Validation

workflows create

workflows import

workflows update

workflows activate / deactivate

workflows trigger

workflows tags

workflows autofix

Fix Types and Confidence Levels

Post-Update Guidance

workflows versions

workflows diff

Supported Operations (17 types)

Smart Parameters for Conditional Nodes

Detailed Operation Examples

workflows deploy-template

nodes

`workflows`

`workflows list`

`workflows get`

`workflows export`

`workflows validate`

`workflows create`

`workflows import`

`workflows update`

`workflows activate` / `deactivate`

`workflows trigger`

`workflows tags`

`workflows autofix`

`workflows versions`

`workflows diff`

`workflows deploy-template`

`nodes`

`nodes list`

`nodes search`

`nodes show`