n8n-cli

English | Español

Official CLI for n8n — search the node catalog, validate workflows, manage workflows and executions via the n8n API, and install AI agent skills for Claude Code, Codex, Cursor, OpenCode, VS Code/Copilot, Windsurf, and Droid.

Attribution: This project is derived from and a contribution to the original n8n-mcp repository by Romuald Członkowski. The core engine, database, and service layer originate from that project.

Table of Contents

• Installation
• Quick Start
• Configuration
• Commands
• Install Skills / Adapters
• Output Formats
• Exit Codes
• Publishing to npm
• Contributing
• Español

Installation

From npm (recommended)

npm install -g @mindbreaker81/n8n-cli
n8n-cli --help

From source (development)

git clone https://github.com/Mindbreaker81/n8n-cli.git
cd n8n-cli
npm install
npm run build
npm install -g .
n8n-cli --help

With npx (no install)

npx @mindbreaker81/n8n-cli --help
npx @mindbreaker81/n8n-cli search nodes --query slack --format json

Quick Start

# 1. Configure your n8n instance (required for API commands)
n8n-cli config set api-url https://your-n8n-instance.com
n8n-cli config set api-key YOUR_API_KEY
# Tip: use env vars to keep keys out of shell history
export N8N_API_URL=https://your-n8n-instance.com
export N8N_API_KEY=YOUR_API_KEY

# 2. Check health
n8n-cli health --format json

# 3. Search the node catalog (offline — no API needed)
n8n-cli search nodes --query slack --limit 5

# 4. List your workflows
n8n-cli workflow list --format table

# 5. Install AI agent skills
n8n-cli install-skills --target claude   # Also: codex, cursor, opencode, vscode, windsurf, droid

Configuration

Precedence (highest to lowest):

1. Environment variables: N8N_API_URL, N8N_API_KEY
2. Config file: ~/.n8n-cli/config.json
3. Defaults

The CLI automatically loads .env from the current directory if present (see .env.example).

# Set via CLI
n8n-cli config set api-url https://your-n8n-instance.com
n8n-cli config set api-key YOUR_API_KEY
n8n-cli config get --format json

Commands

Catalog & Docs (offline — no API needed)

| Command | Description | |---------|-------------| | search nodes --query <text> | Full-text search across the node catalog | | node details --type <nodeType> | Node properties, options, and metadata | | node operations --type <nodeType> | Available resources and actions | | node docs --type <nodeType> | Markdown documentation for a node | | node examples --type <nodeType> | Configuration examples from templates | | template search --query <text> | Search workflow templates | | template get --id <id> | Retrieve a template by ID | | validate node --type <t> --config <json> | Validate a node configuration | | validate workflow --file <path> | Validate a full workflow JSON | | docs [topic] | Show documentation topics | | health | CLI health check (optionally pings n8n API) |

Workflow Management (requires API)

| Command | Description | |---------|-------------| | workflow list | List workflows (--limit, --cursor, --active, --tags) | | workflow get --id <id> | Get a workflow by ID (--mode full\|details\|structure\|minimal) | | workflow create --name <n> --nodes <json> --connections <json> | Create a workflow | | workflow update --id <id> --full | Full workflow replacement | | workflow update --id <id> --partial --operations <json> | Partial update via operations | | workflow delete --id <id> | Delete a workflow | | workflow trigger --id <id> | Trigger a workflow via webhook/form/chat |

Execution Management (requires API)

| Command | Description | |---------|-------------| | exec list --workflow-id <id> | List executions for a workflow | | exec get --id <id> | Get execution details | | exec delete --id <id> | Delete an execution |

Utilities

| Command | Description | |---------|-------------| | config set api-url <url> | Set n8n API URL | | config set api-key <key> | Set n8n API key | | config get | Show current config (key masked) | | install-skills --target <target> | Install AI agent skills | | doctor | Diagnose CLI installation and configuration |

Install Skills / Adapters

Install slash commands and AI agent adapters for your preferred IDE:

# Claude Code slash commands → ~/.claude/commands/
n8n-cli install-skills --target claude

# Codex.app skill → ~/.codex/skills/
n8n-cli install-skills --target codex

# Cursor IDE rule → ~/.cursor/rules/
n8n-cli install-skills --target cursor

# OpenCode, VS Code/Copilot, Windsurf, Droid (same SKILL.md format as Codex)
n8n-cli install-skills --target opencode   # → ~/.config/opencode/skills/
n8n-cli install-skills --target vscode     # → ~/.copilot/skills/
n8n-cli install-skills --target windsurf  # → ~/.codeium/windsurf/skills/
n8n-cli install-skills --target droid     # → ~/.factory/skills/

# Preview without installing
n8n-cli install-skills --target claude --dry-run --format json

Available Skills

| Category | Skills | |----------|--------| | Setup | /n8n-setup | | Catalog (offline) | /n8n-search, /n8n-node-details, /n8n-node-operations, /n8n-node-docs, /n8n-node-examples, /n8n-template-search, /n8n-template-get, /n8n-validate-node, /n8n-validate-workflow | | Workflow & Exec (API) | /n8n-workflow-create, /n8n-workflow-get, /n8n-workflow-update, /n8n-workflow-delete, /n8n-workflow-list, /n8n-workflow-trigger, /n8n-exec-get, /n8n-exec-list, /n8n-exec-delete, /n8n-health | | Composite | /n8n-build, /n8n-debug, /n8n-scaffold, /n8n-audit, /n8n-migrate, /n8n-ops |

Custom install paths (optional)

export N8N_MCP_CLAUDE_COMMANDS_PATH=/custom/path/commands
export N8N_MCP_CODEX_SKILLS_PATH=/custom/path/skills
export N8N_MCP_CURSOR_RULES_PATH=/custom/path/rules
export N8N_MCP_OPENCODE_SKILLS_PATH=/custom/path/opencode/skills
export N8N_MCP_VSCODE_SKILLS_PATH=/custom/path/vscode/skills
export N8N_MCP_WINDSURF_SKILLS_PATH=/custom/path/windsurf/skills
export N8N_MCP_DROID_SKILLS_PATH=/custom/path/droid/skills

See n8n-mcp-skills/README.md for the full skills documentation.

Output Formats

--format json    # Machine-readable JSON (default in non-TTY / pipes)
--format table   # Human-readable table (default in TTY)
--format yaml    # YAML output
--no-color       # Disable ANSI colors
-q, --quiet      # Data only, no status messages
-v, --verbose    # Extra output (paths, timings)

Note: --format must be placed on the subcommand, not the root command:

n8n-cli search nodes --query slack --format json   ✓  correct
n8n-cli --format json search nodes --query slack   ✗  not parsed

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General / not found error | | 2 | Auth / config error | | 3 | Validation failed | | 4 | Network / API error |

Error JSON format (on stderr when exit code ≠ 0):

{
  "error": true,
  "code": "AUTH_REQUIRED",
  "message": "API key is required",
  "suggestion": "Run: n8n-cli config set api-key <key>"
}

Publishing to npm

See PUBLISH-N8N-CLI-NPM.md for the full publishing guide.

npm install && npm run build && npm test
npm login
npm publish --access public --otp=<YOUR_OTP>

What's included in the npm package: dist/**/*, data/nodes.db, n8n-mcp-skills/**/*, README.md, LICENSE, CHANGELOG.md, .env.example.

Note: data/nodes.db is generated from the n8n node catalog via the n8n-mcp rebuild pipeline and must be obtained separately before publishing. See PUBLISH-N8N-CLI-NPM.md for instructions.

Contributing

Contributions are welcome. Please open an issue or pull request on GitHub.

This project is a contribution to and derived from czlonkowski/n8n-mcp.

Related Documentation

| File | Description | |------|-------------| | CLI-AND-SKILLS.md | Architecture and CLI↔MCP tool mapping | | PUBLISH-N8N-CLI-NPM.md | Full npm publishing guide | | TESTING-CLI-AGAINST-N8N.md | E2E testing guide | | CHANGELOG.md | Change history | | n8n-mcp-skills/README.md | Skills and adapters documentation | | CLAUDE.md | AI assistant reference for this codebase |

Español

English | Español

CLI oficial para n8n — busca el catálogo de nodos, valida workflows, gestiona workflows y ejecuciones vía la API de n8n, e instala skills de agentes IA para Claude Code, Codex y Cursor.

Atribución: Este proyecto es una derivación y contribución al repositorio original n8n-mcp de Romuald Członkowski. El motor principal, la base de datos y la capa de servicios proceden de ese proyecto.

Instalación

# Desde npm (recomendado)
npm install -g @mindbreaker81/n8n-cli
n8n-cli --help

# Desde el código fuente (desarrollo)
git clone https://github.com/Mindbreaker81/n8n-cli.git
cd n8n-cli
npm install && npm run build && npm install -g .

# Con npx (sin instalación global)
npx @mindbreaker81/n8n-cli --help

Inicio rápido

# 1. Configurar la instancia n8n (necesario para comandos de API)
n8n-cli config set api-url https://tu-instancia-n8n.com
n8n-cli config set api-key TU_API_KEY
# Recomendado: usa variables de entorno
export N8N_API_URL=https://tu-instancia-n8n.com
export N8N_API_KEY=TU_API_KEY

# 2. Comprobar estado
n8n-cli health --format json

# 3. Buscar en el catálogo (sin conexión, no necesita API)
n8n-cli search nodes --query slack --limit 5

# 4. Listar workflows
n8n-cli workflow list --format table

# 5. Instalar skills para agentes IA
n8n-cli install-skills --target claude   # También: codex, cursor, opencode, vscode, windsurf, droid

Configuración

Precedencia (de mayor a menor):

1. Variables de entorno: N8N_API_URL, N8N_API_KEY
2. Archivo de config: ~/.n8n-cli/config.json
3. Valores por defecto

n8n-cli config set api-url https://tu-instancia-n8n.com
n8n-cli config set api-key TU_API_KEY
n8n-cli config get --format json

Comandos principales

Catálogo y documentación (sin conexión)

| Comando | Descripción | |---------|-------------| | search nodes --query <texto> | Búsqueda en el catálogo de nodos | | node details\|operations\|docs\|examples --type <tipo> | Info del nodo | | template search\|get | Plantillas de workflows | | validate node\|workflow | Validación local | | health | Estado de la CLI |

Gestión de workflows (requiere API)

| Comando | Descripción | |---------|-------------| | workflow list\|get\|create\|update\|delete\|trigger | CRUD de workflows | | exec list\|get\|delete | Gestión de ejecuciones |

Utilidades

| Comando | Descripción | |---------|-------------| | config set\|get | Configuración de la CLI | | install-skills --target claude\|codex\|cursor\|opencode\|vscode\|windsurf\|droid | Instalar skills para IA | | doctor | Diagnóstico de instalación |

Instalar skills y adaptadores

n8n-cli install-skills --target claude   # → ~/.claude/commands/
n8n-cli install-skills --target codex   # → ~/.codex/skills/
n8n-cli install-skills --target cursor   # → ~/.cursor/rules/
n8n-cli install-skills --target opencode # → ~/.config/opencode/skills/
n8n-cli install-skills --target vscode   # → ~/.copilot/skills/
n8n-cli install-skills --target windsurf # → ~/.codeium/windsurf/skills/
n8n-cli install-skills --target droid   # → ~/.factory/skills/
n8n-cli install-skills --target claude --dry-run --format json  # previsualización

Formatos de salida

--format json    # JSON (por defecto en pipes/no-TTY)
--format table   # Tabla (por defecto en TTY)
--format yaml    # YAML
--no-color       # Sin colores ANSI
-q, --quiet      # Solo datos, sin mensajes adicionales
-v, --verbose    # Salida detallada (rutas, tiempos)

Códigos de salida

| Código | Significado | |--------|-------------| | 0 | Éxito | | 1 | Error general | | 2 | Auth/config | | 3 | Validación fallida | | 4 | Red/API |

Formato de error JSON (stderr cuando exit code ≠ 0)

{
  "error": true,
  "code": "AUTH_REQUIRED",
  "message": "Se requiere API key",
  "suggestion": "Ejecuta: n8n-cli config set api-key <clave>"
}

Publicar en npm

Guía completa: PUBLISH-N8N-CLI-NPM.md

npm install && npm run build && npm test
npm login
npm publish --access public --otp=<TU_OTP>

Documentación relacionada

| Archivo | Descripción | |---------|-------------| | CLI-AND-SKILLS.md | Arquitectura y mapeo CLI↔MCP | | PUBLISH-N8N-CLI-NPM.md | Guía de publicación en npm | | CHANGELOG.md | Historial de cambios | | n8n-mcp-skills/README.md | Skills y adaptadores | | CLAUDE.md | Referencia para asistentes IA |

Conceived by Romuald Członkowski – www.aiadvisors.pl/en Maintained by Mindbreaker81