ubie-oss/n8n-cli

Skill de Operaciones n8n-cli

Una skill para ayudar en la gestión de flujos de trabajo usando n8n-cli (TypeScript/Bun).

Inicialización de Sesión (Importante)

Para nuevas sesiones, siempre ejecuta lo siguiente primero para asegurar que n8n-cli esté actualizado.

Prioridad 1: Compilar desde Fuente Local (Desarrollo)

Si el repositorio fuente de n8n-cli está disponible mediante add-dir (por ejemplo, existe /ruta/a/n8n-cli/Makefile), compila desde la fuente local en lugar de usar un lanzamiento. Esto asegura que los últimos cambios de desarrollo se reflejen inmediatamente.

# Si el repositorio n8n-cli es visible mediante add-dir
N8N_CLI_REPO="/ruta/a/n8n-cli"  # Reemplaza con la ruta de add-dir
if [ -f "$N8N_CLI_REPO/Makefile" ]; then
  echo "Compilando n8n-cli desde fuente local: $N8N_CLI_REPO"
  cd "$N8N_CLI_REPO" && bun install && make build
  cp "$N8N_CLI_REPO/n8n-cli" /ruta/a/destino/n8n-cli
  cd /ruta/a/destino
  echo "Compilado desde fuente local: $(./n8n-cli version 2>/dev/null | head -1)"
fi

Prioridad 2: Auto-actualización desde GitHub Releases (Preferido)

Los binarios precompilados están disponibles en GitHub Releases. Esto es más rápido que compilar desde la fuente y asegura que estés usando el lanzamiento oficial.

# 1. Verifica la versión del último lanzamiento
LATEST_TAG=$(gh release view --repo ubie-oss/n8n-cli --json tagName -q '.tagName' 2>/dev/null)

# 2. Verifica la versión local actual (si el binario existe)
CURRENT_VERSION=""
if [ -x ./n8n-cli ]; then
  CURRENT_VERSION=$(./n8n-cli version 2>/dev/null | head -1 | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "")
fi

# 3. Compara y descarga si es necesario
if [ -z "$CURRENT_VERSION" ] || [ "$CURRENT_VERSION" != "$LATEST_TAG" ]; then
  echo "Actualizando n8n-cli: ${CURRENT_VERSION:-ninguna} -> ${LATEST_TAG}"

  # Detecta la plataforma
  ARCH=$(uname -m)
  OS=$(uname -s | tr '[:upper:]' '[:lower:]')
  case "$ARCH" in
    arm64|aarch64) ASSET_NAME="n8n-cli-${OS}-arm64" ;;
    x86_64)        ASSET_NAME="n8n-cli-${OS}-x64" ;;
    *)             echo "Arquitectura no soportada: $ARCH"; exit 1 ;;
  esac

  # Descarga el binario
  gh release download "$LATEST_TAG" --repo ubie-oss/n8n-cli --pattern "$ASSET_NAME" --output n8n-cli --clobber
  chmod +x ./n8n-cli
  echo "Actualizado a $(./n8n-cli version 2>/dev/null | head -1)"
else
  echo "n8n-cli está actualizado: $CURRENT_VERSION"
fi

Plan de Contingencia: Compilar desde Fuente

Si el CLI gh no está disponible o necesitas una compilación de desarrollo:

# Instala dependencias + compila el CLI
bun install && make build

Verificación de la compilación:

./n8n-cli version

Configuración del Entorno

Verificación del Archivo .env

Si .env existe en la raíz del proyecto, n8n-cli se puede usar sin especificar parámetros. No leas el contenido.

# Solo verifica la existencia de .env (no leas el contenido)
test -f .env && echo ".env existe - n8n-cli se puede usar sin parámetros"

Si .env existe:

• N8N_API_URL y N8N_API_KEY ya están configurados
• ./n8n-cli se puede ejecutar sin parámetros

Si .env no existe:

• Solicita al usuario que cree un archivo .env
• O usa las banderas --api-url y --api-key

Creación de .env (Solo si es Necesario)

cp .env.example .env
# Pide al usuario que edite

Comandos Comunes

1. Verificación del Estado de un Flujo de Trabajo Remoto

Verifica un flujo de trabajo específico:

# Obtén información del flujo de trabajo por ID
./n8n-cli workflow get <workflow-id>

# Muestra en formato tabla para legibilidad
./n8n-cli -o table workflow get <workflow-id>

# Guarda en un archivo (útil para comparación de diferencias)
./n8n-cli workflow get <workflow-id> > /tmp/remote-workflow.json

Lista flujos de trabajo:

# Todos los flujos de trabajo
./n8n-cli workflow list

# Formato tabla
./n8n-cli -o table workflow list

# Solo activos
./n8n-cli workflow list --active

2. Importación de Flujos de Trabajo (Remoto -> Local)

Verificar el Formato Local Antes de Importar

Al extraer contenido remoto a local, sigue siempre estos pasos:

1. Verifica el formato del archivo local

   # Verifica si el archivo existe y su formato
   ls -la definitions/*<workflow-id>* definitions/**/*<workflow-id>*
   
   

2. Usa las opciones de importación apropiadas según el formato

   • Archivos .json: usa solo --ids
   • Archivos .yaml/.yml: usa tanto --ids como --yaml

Importa un flujo de trabajo específico:

# Flujo de trabajo en formato JSON
./n8n-cli import --ids=<workflow-id>

# Flujo de trabajo en formato YAML
./n8n-cli import --ids=<workflow-id> --yaml

# A un directorio personalizado
./n8n-cli import --ids=<workflow-id> -d ./my-dir

Importa múltiples flujos de trabajo:

# Lista separada por comas
./n8n-cli import --ids=abc123,def456,ghi789

Importa todos los flujos de trabajo:

./n8n-cli import

Opciones adicionales:

Opción	Descripción
--include-archived	Incluir flujos de trabajo archivados
--cleanup-orphans	Eliminar archivos huérfanos sin IDs coincidentes
-t, --threshold <int>	Líneas mínimas para extracción de archivos externos (por defecto: 0, configurable en CLAUDE.md)
--dry-run	Solo vista previa (sin cambios en archivos)
--tags <tags>	Filtrar por nombres de etiquetas separados por comas (condición AND)

3. Ejecución de Prueba (Vista Previa de Cambios)

Siempre verifica con una ejecución de prueba antes de aplicar:

# Vista previa de cambios para todos los flujos de trabajo
./n8n-cli apply --dry-run

# Solo flujo de trabajo específico (por ID)
./n8n-cli apply --dry-run --ids=<workflow-id>

# Solo archivo específico
./n8n-cli apply --dry-run -d definitions/path/to/workflow.json

Ejemplo de salida:

=== CREAR (1 flujo de trabajo) ===
  + new-workflow.json (nombre: "Nueva Automatización")

=== ACTUALIZAR (2 flujos de trabajo) ===
  ~ existing.json (id: R2cTI0LDzCJSnvNG)
    - name: "Nombre Antiguo" -> "Nombre Nuevo"
    - nodes: 3 -> 5 nodos

=== SALTAR (1 flujo de trabajo) ===
  = unchanged.json (sin cambios)

Resumen (dry-run): 1 para crear, 2 para actualizar, 1 sin cambios

4. Aplicar (Desplegar)

Los asistentes de IA deben usar siempre --ids

# Aplica solo un flujo de trabajo específico (recomendado)
./n8n-cli apply --ids=<workflow-id>

# Aplica solo un archivo específico
./n8n-cli apply -d definitions/path/to/workflow.json

# Forzar aplicación (sobrescribir cambios remotos)
./n8n-cli apply --ids=<workflow-id> --force

Prohibido: Aplicar a un directorio completo

# Estos NO deben ser ejecutados por IA
./n8n-cli apply -d definitions/
./n8n-cli apply

Opciones adicionales:

Opción	Descripción
--from-git-changes <spec>	Aplicar solo los archivos cambiados en la diferencia de Git
--yaml / --no-yaml	Habilitar/deshabilitar procesamiento YAML
--allow-duplicates	Saltar la verificación upstream de nombre duplicado (por defecto: activado; usa --force para empujar a través de advertencias en lugar de deshabilitar la verificación)
--no-auto-tag	Deshabilitar etiquetado automático (gestionado-como-código)
-p, --project <id>	Especificar ID del proyecto destino

Variables de entorno:

• APPLY_FILTER_BY_TAGS - Filtrar por nombres de etiquetas separados por comas (condición AND)

Modo de diferencia Git:

# Aplicar solo cambios de una rama de funcionalidad
./n8n-cli apply --from-git-changes origin/main..HEAD

# Vista previa
./n8n-cli apply --from-git-changes origin/main..HEAD --dry-run

# Cambios de los últimos 3 commits
./n8n-cli apply --from-git-changes HEAD~3..HEAD

Detección de conflictos 3-way: Cuando se especifica --from-git-changes, los conflictos se detectan comparando Base (punto de referencia), Local (actual) y Remoto (servidor) para identificar solo los conflictos reales.

5. Linter (Verificaciones de Calidad)

El linter está integrado en el CLI. No se necesita compilación separada.

Nota: Los argumentos posicionales no están soportados. Siempre especifica archivos/directorios con -f o -d.

# Verifica un archivo específico (-f requerido)
./n8n-cli lint -f definitions/<filename>

# Verifica un directorio específico
./n8n-cli lint -d ./definitions/example-project

# Verifica todos los flujos de trabajo
./n8n-cli lint -d ./definitions

# Salida JSON (para CI/CD)
./n8n-cli lint -d ./definitions -o json

Opciones:

Opción	Descripción
-d, --dir <path>	Directorio de archivos de definición
-f, --file <archivos...>	Archivo(s) específico(s)
-c, --config <path>	Ruta del archivo de configuración (.n8nlintrc.json)
--disable-rule <nombre>	Deshabilitar regla(s) específica(s)
--list-rules	Listar todas las reglas
-o, --output <formato>	Formato de salida: text, json (por defecto: text)

Reglas (11 reglas):

Regla	Gravedad	Descripción
json-syntax	error	Verificación de sintaxis JSON
required-fields	error	Verificación de campos requeridos (nombre, nodes, connections)
connection-reference	error	Verificación de existencia del nodo destino de la conexión
webhook-id-required	error	Verificar que los nodos webhook y formTrigger tengan el campo webhookId
orphaned-node	warning	Detección de nodos huérfanos
implicit-json-ref	warning	Detección de referencia implícita $json
expression-mode-prefix	warning	Detección de prefijo = faltante
ai-agent-output-ref	warning	Detección de referencia incorrecta a salida de AI Agent
node-params	warning	Validación de esquema de parámetros del nodo
node-ref-field-check	warning	Validación de existencia de campo referenciado
node-ref-cardinality	warning	Validación de uso de .item/.first()

Archivo de configuración (.n8nlintrc.json):

{
  "rules": {
    "json-syntax": "error",
    "required-fields": "error",
    "orphaned-node": "warning",
    "implicit-json-ref": "off"
  }
}

Orden de búsqueda del archivo de configuración:

1. Ruta especificada con la bandera --config
2. .n8nlintrc.json / .n8nlintrc en el directorio destino
3. .n8nlintrc.json / .n8nlintrc en el directorio actual

6. Formateador (Auto-formato)

Nota: fmt toma argumentos posicionales para archivos (sin opción -f).

# Formatea un archivo específico (argumento posicional)
./n8n-cli fmt definitions/<filename>

# Múltiples archivos
./n8n-cli fmt definitions/file1.yaml definitions/file2.yaml

# Formatea un directorio completo
./n8n-cli fmt -d ./definitions

# Solo vista previa
./n8n-cli fmt -d ./definitions --dry-run

7. Prueba (Ejecución)

Prueba flujos de trabajo mediante webhooks de prueba:

# Prueba básica
./n8n-cli test <workflow-id>

# Con datos de prueba
./n8n-cli test <workflow-id> -d '{"email": "[email protected]"}'

# Espera a que la ejecución se complete (recomendado)
./n8n-cli test <workflow-id> --wait-execution

# Auto-activar flujos de trabajo inactivos
./n8n-cli test <workflow-id> --activate

# Verificar solo la URL del webhook
./n8n-cli test <workflow-id> --dry-run

# Verificar parámetros de entrada
./n8n-cli test <workflow-id> --show-inputs

Opciones:

Opción	Descripción
-d, --data <json>	Datos de prueba (cadena JSON)
--timeout <duración>	Tiempo de espera HTTP (por defecto: 30s)
--wait-execution	Esperar a que la ejecución se complete y mostrar resultados
--activate	Auto-activar flujos de trabajo inactivos
--dry-run	Verificar solo la URL del webhook
--show-inputs	Mostrar parámetros de entrada
-o, --output <fmt>	Formato de salida: json, table (por defecto: json)

Prueba desde un archivo local:

# Especifica un archivo JSON/YAML local
./n8n-cli test ./definitions/my-workflow.json

8. Ejecución (Registros y Errores)

Listar ejecuciones recientes:

# Listar todas las ejecuciones recientes
./n8n-cli execution list

# Formato tabla para legibilidad
./n8n-cli -o table execution list

# Filtrar por estado
./n8n-cli execution list --status error
./n8n-cli execution list --status success

# Filtrar por flujo de trabajo
./n8n-cli execution list --workflow <workflow-id>

# Limitar resultados
./n8n-cli execution list --limit 5

# Filtros combinados
./n8n-cli execution list --workflow <workflow-id> --status error --limit 10

Obtener detalles de la ejecución:

# Obtener ejecución por ID
./n8n-cli execution get <execution-id>

# Formato tabla con detalles de error
./n8n-cli -o table execution get <execution-id>

# Incluir resumen de ejecución de nodos
./n8n-cli -o table execution get <execution-id> --show-data

Opciones para execution list:

Opción	Descripción
-w, --workflow <id>	Filtrar por ID de flujo de trabajo
-s, --status <estado>	Filtrar por estado (success, error, running, waiting)
-l, --limit <n>	Número máximo de ejecuciones (por defecto: 20)

Opciones para execution get:

Opción	Descripción
--show-data	Incluir resumen de ejecución de nodos en la salida

Información de error mostrada:

Campo	Descripción
Nodo de Error	El nodo donde ocurrió el error
Mensaje de Error	El mensaje de error
Detalles del Error	Descripción adicional del error (si está disponible)
Último Nodo	El último nodo ejecutado

Flujo de trabajo típico de depuración:

# 1. Listar errores recientes
./n8n-cli -o table execution list --status error --limit 5

# 2. Obtener detalles de una ejecución fallida específica
./n8n-cli -o table execution get <execution-id> --show-data

# 3. Revisar detalles del error y corregir el flujo de trabajo

9. Convertir (Conversión de Formato)

Convertir archivos de flujo de trabajo entre formatos JSON y YAML (solo local, no necesita API):

# Convertir todos los flujos de trabajo JSON a YAML
./n8n-cli convert -d ./definitions --format yaml

# Convertir flujos de trabajo específicos por ID
./n8n-cli convert -d ./definitions --format json --ids <workflow-id>

# Vista previa sin escribir
./n8n-cli convert -d ./definitions --format yaml --dry-run

# Mantener archivos originales
./n8n-cli convert -d ./definitions --format yaml --keep

# Convertir un solo archivo
./n8n-cli convert --format yaml definitions/<filename>.json

Opciones:

Opción	Descripción
--format <formato>	Formato destino: json, yaml (requerido)
-d, --directory <dir>	Directorio para escanear archivos de flujo de trabajo
--ids <ids>	IDs de flujo de trabajo separados por comas para convertir
--tags <tags>	Filtrar por etiquetas (separadas por comas, condición AND)
-t, --threshold <n>	Líneas mínimas para externalización de código (JSON→YAML)
--dry-run	Solo vista previa
--keep	Mantener archivos originales

Comportamiento:

• JSON→YAML: genera YAML + _subfiles/ con código externalizado
• YAML→JSON: resuelve referencias !include y elimina _subfiles/
• Los archivos ya en el formato destino se saltan
• Los archivos originales se eliminan después de la conversión a menos que se use --keep

10. Tablas de Datos

Gestionar tablas y filas de datos:

# Listar todas las tablas de datos
./n8n-

...

[truncado para traducción]