npm package: @mindbreaker81/n8n-cli
Description: Official CLI for n8n — node catalog search, workflow management, validation, and AI agent skills for Claude Code, Codex, Cursor, OpenCode, VS Code, Windsurf, and Droid
Author: Romuald Czlonkowski @ www.aiadvisors.pl/en
Latest version: 1.0.3

# n8n-cli

**English** | [Español](#español)

---

Official CLI for [n8n](https://n8n.io) — 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](https://github.com/czlonkowski/n8n-mcp) repository by [Romuald Członkowski](https://www.aiadvisors.pl/en). The core engine, database, and service layer originate from that project.

[![npm version](https://img.shields.io/npm/v/@mindbreaker81/n8n-cli.svg)](https://www.npmjs.com/package/@mindbreaker81/n8n-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)

---

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Commands](#commands)
- [Install Skills / Adapters](#install-skills--adapters)
- [Output Formats](#output-formats)
- [Exit Codes](#exit-codes)
- [Publishing to npm](#publishing-to-npm)
- [Contributing](#contributing)
- [Español](#español)

---

## Installation

### From npm (recommended)

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

### From source (development)

```bash
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)

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

---

## Quick Start

```bash
# 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`).

```bash
# 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:

```bash
# 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)

```bash
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](./n8n-mcp-skills/README.md) for the full skills documentation.

---

## Output Formats

```bash
--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:
```bash
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):

```json
{
  "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](./PUBLISH-N8N-CLI-NPM.md) for the full publishing guide.

```bash
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](https://github.com/czlonkowski/n8n-mcp) rebuild pipeline and must be obtained separately before publishing. See [PUBLISH-N8N-CLI-NPM.md](./PUBLISH-N8N-CLI-NPM.md) for instructions.

---

## Contributing

Contributions are welcome. Please open an issue or pull request on [GitHub](https://github.com/Mindbreaker81/n8n-cli).

This project is a contribution to and derived from [czlonkowski/n8n-mcp](https://github.com/czlonkowski/n8n-mcp).

---

## Related Documentation

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

---

---

# Español

**[English](#n8n-cli)** | Español

---

CLI oficial para [n8n](https://n8n.io) — 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](https://github.com/czlonkowski/n8n-mcp) de [Romuald Członkowski](https://www.aiadvisors.pl/en). El motor principal, la base de datos y la capa de servicios proceden de ese proyecto.

---

## Instalación

```bash
# 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

```bash
# 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

```bash
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

```bash
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

```bash
--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)

```json
{
  "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](./PUBLISH-N8N-CLI-NPM.md)

```bash
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](./CLI-AND-SKILLS.md) | Arquitectura y mapeo CLI↔MCP |
| [PUBLISH-N8N-CLI-NPM.md](./PUBLISH-N8N-CLI-NPM.md) | Guía de publicación en npm |
| [CHANGELOG.md](./CHANGELOG.md) | Historial de cambios |
| [n8n-mcp-skills/README.md](./n8n-mcp-skills/README.md) | Skills y adaptadores |
| [CLAUDE.md](./CLAUDE.md) | Referencia para asistentes IA |

---

Conceived by Romuald Członkowski – [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
Maintained by [Mindbreaker81](https://github.com/Mindbreaker81)