Skill n8n-cli Operations

Un skill pour assister à la gestion des workflows avec n8n-cli (TypeScript/Bun).

Initialisation de la Session (Important)

Pour les nouvelles sessions, exécutez toujours ce qui suit en premier afin de garantir que n8n-cli est à jour.

Priorité 1 : Construction depuis la Source Locale (Développement)

Si le dépôt source de n8n-cli est disponible via add-dir (par exemple, /chemin/vers/n8n-cli/Makefile existe), construisez à partir de la source locale plutôt que d'utiliser une version. Cela garantit que les dernières modifications de développement sont reflétées immédiatement.

# Si le dépôt n8n-cli est visible via add-dir
N8N_CLI_REPO="/chemin/vers/n8n-cli"  # Remplacez par le chemin add-dir
if [ -f "$N8N_CLI_REPO/Makefile" ]; then
  echo "Construction de n8n-cli depuis la source locale : $N8N_CLI_REPO"
  cd "$N8N_CLI_REPO" && bun install && make build
  cp "$N8N_CLI_REPO/n8n-cli" /chemin/vers/cible/n8n-cli
  cd /chemin/vers/cible
  echo "Construit depuis la source locale : $(./n8n-cli version 2>/dev/null | head -1)"
fi

Priorité 2 : Mise à Jour Automatique depuis les Versions GitHub (Recommandé)

Les binaires pré-construits sont disponibles dans les Versions GitHub. C'est plus rapide que de construire depuis la source et garantit que vous utilisez la version officielle.

# 1. Vérifier la dernière version
DERNIERE_VERSION=$(gh release view --repo ubie-oss/n8n-cli --json tagName -q '.tagName' 2>/dev/null)

# 2. Vérifier la version locale actuelle (si le binaire existe)
VERSION_ACTUELLE=""
if [ -x ./n8n-cli ]; then
  VERSION_ACTUELLE=$(./n8n-cli version 2>/dev/null | head -1 | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "")
fi

# 3. Comparer et télécharger si nécessaire
if [ -z "$VERSION_ACTUELLE" ] || [ "$VERSION_ACTUELLE" != "$DERNIERE_VERSION" ]; then
  echo "Mise à jour de n8n-cli : ${VERSION_ACTUELLE:-aucune} -> ${DERNIERE_VERSION}"

  # Détection de la plateforme
  ARCH=$(uname -m)
  OS=$(uname -s | tr '[:upper:]' '[:lower:]')
  case "$ARCH" in
    arm64|aarch64) NOM_ACTIF="n8n-cli-${OS}-arm64" ;;
    x86_64)        NOM_ACTIF="n8n-cli-${OS}-x64" ;;
    *)             echo "Architecture non prise en charge : $ARCH"; exit 1 ;;
  esac

  # Télécharger le binaire
  gh release download "$DERNIERE_VERSION" --repo ubie-oss/n8n-cli --pattern "$NOM_ACTIF" --output n8n-cli --clobber
  chmod +x ./n8n-cli
  echo "Mis à jour vers $(./n8n-cli version 2>/dev/null | head -1)"
else
  echo "n8n-cli est à jour : $VERSION_ACTUELLE"
fi

Solution de Repli : Construction depuis la Source

Si l'interface CLI gh n'est pas disponible ou si vous avez besoin d'une version de développement :

# Installer les dépendances + construire le CLI
bun install && make build

Vérification de la construction :

./n8n-cli version

Configuration de l'Environnement

Vérification du Fichier .env

Si .env existe à la racine du projet, n8n-cli peut être utilisé sans spécifier de paramètres. Ne lisez pas le contenu.

# Vérifier uniquement l'existence de .env (ne pas lire le contenu)
test -f .env && echo ".env existe - n8n-cli peut être utilisé sans paramètres"

Si .env existe :

N8N_API_URL et N8N_API_KEY sont déjà configurés
./n8n-cli peut être exécuté sans paramètres

Si .env n'existe pas :

Demandez à l'utilisateur de créer un fichier .env
Ou utilisez les options --api-url et --api-key

Création de .env (Uniquement si Nécessaire)

cp .env.example .env
# Demandez à l'utilisateur de modifier

Commandes Courantes

1. Vérification de l'État du Workflow Distant

Vérifier un workflow spécifique :

# Obtenir les informations d'un workflow par son ID
./n8n-cli workflow get <id-du-workflow>

# Afficher au format tableau pour une meilleure lisibilité
./n8n-cli -o table workflow get <id-du-workflow>

# Enregistrer dans un fichier (utile pour les comparaisons de différences)
./n8n-cli workflow get <id-du-workflow> > /tmp/workflow-distant.json

Lister les workflows :

# Tous les workflows
./n8n-cli workflow list

# Format tableau
./n8n-cli -o table workflow list

# Actifs uniquement
./n8n-cli workflow list --active

2. Importer des Workflows (Distant -> Local)

Vérifier le Format Local Avant l'Importation

Lorsque vous récupérez du contenu distant en local, suivez toujours ces étapes :

Vérifier le format du fichier local

# Vérifier si le fichier existe et son format
ls -la definitions/*<id-du-workflow>* definitions/**/*<id-du-workflow>*

Utiliser les options d'importation appropriées selon le format
- Fichiers .json : utilisez uniquement --ids
- Fichiers .yaml/.yml : utilisez à la fois --ids et --yaml

Importer un workflow spécifique :

# Workflow au format JSON
./n8n-cli import --ids=<id-du-workflow>

# Workflow au format YAML
./n8n-cli import --ids=<id-du-workflow> --yaml

# Vers un répertoire personnalisé
./n8n-cli import --ids=<id-du-workflow> -d ./mon-dossier

Importer plusieurs workflows :

# Liste séparée par des virgules
./n8n-cli import --ids=abc123,def456,ghi789

Importer tous les workflows :

./n8n-cli import

Options supplémentaires :

Option	Description
`--include-archived`	Inclure les workflows archivés
`--cleanup-orphans`	Supprimer les fichiers orphelins sans ID correspondant
`-t, --threshold <int>`	Nombre minimum de lignes pour l'extraction de fichier externe (par défaut : 0, configurable dans CLAUDE.md)
`--dry-run`	Aperçu uniquement (aucune modification de fichier)
`--tags <tags>`	Filtrer par noms de balises séparés par des virgules (condition ET)

3. Dry-run (Aperçu des Modifications)

Vérifiez toujours avec dry-run avant d'appliquer :

# Aperçu des modifications pour tous les workflows
./n8n-cli apply --dry-run

# Workflow spécifique uniquement (par ID)
./n8n-cli apply --dry-run --ids=<id-du-workflow>

# Fichier spécifique uniquement
./n8n-cli apply --dry-run -d definitions/chemin/vers/workflow.json

Exemple de sortie :

=== CRÉATION (1 workflow) ===
  + nouveau-workflow.json (nom : "Nouvelle Automatisation")

=== MISE À JOUR (2 workflows) ===
  ~ existant.json (id : R2cTI0LDzCJSnvNG)
    - nom : "Ancien Nom" -> "Nouveau Nom"
    - nœuds : 3 -> 5 nœuds

=== IGNORÉ (1 workflow) ===
  = inchangé.json (aucune modification)

Résumé (dry-run) : 1 à créer, 2 à mettre à jour, 1 inchangé

4. Appliquer (Déploiement)

Les assistants IA doivent toujours utiliser --ids

# Appliquer un workflow spécifique uniquement (recommandé)
./n8n-cli apply --ids=<id-du-workflow>

# Appliquer un fichier spécifique uniquement
./n8n-cli apply -d definitions/chemin/vers/workflow.json

# Forcer l'application (écraser les modifications distantes)
./n8n-cli apply --ids=<id-du-workflow> --force

Interdit : Appliquer à un répertoire entier

# Ces commandes ne doivent PAS être exécutées par une IA
./n8n-cli apply -d definitions/
./n8n-cli apply

Options supplémentaires :

Option	Description
`--from-git-changes <spec>`	Appliquer uniquement les fichiers modifiés dans le diff Git
`--yaml` / `--no-yaml`	Activer/désactiver le traitement YAML
`--allow-duplicates`	Ignorer la vérification de noms en double en amont (par défaut : activé ; utilisez `--force` pour passer outre les avertissements au lieu de désactiver la vérification)
`--no-auto-tag`	Désactiver le balisage automatique (managed-as-code)
`-p, --project <id>`	Spécifier l'ID du projet cible

Variables d'environnement :

APPLY_FILTER_BY_TAGS - Filtrer par noms de balises séparés par des virgules (condition ET)

Mode diff Git :

# Appliquer uniquement les modifications d'une branche de fonctionnalité
./n8n-cli apply --from-git-changes origin/main..HEAD

# Aperçu
./n8n-cli apply --from-git-changes origin/main..HEAD --dry-run

# Modifications des 3 derniers commits
./n8n-cli apply --from-git-changes HEAD~3..HEAD

Détection de conflit à 3 voies : Lorsque --from-git-changes est spécifié, les conflits sont détectés en comparant la Base (point de référence), le Local (actuel) et le Distant (serveur) pour identifier uniquement les vrais conflits.

5. Linter (Contrôles de Qualité)

Le linter est intégré au CLI. Aucune construction séparée nécessaire.

Remarque : Les arguments positionnels ne sont pas pris en charge. Spécifiez toujours les fichiers/répertoires avec -f ou -d.

# Vérifier un fichier spécifique (-f requis)
./n8n-cli lint -f definitions/<nom_fichier>

# Vérifier un répertoire spécifique
./n8n-cli lint -d ./definitions/projet-exemple

# Vérifier tous les workflows
./n8n-cli lint -d ./definitions

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

Options :

Option	Description
`-d, --dir <chemin>`	Répertoire des fichiers de définition
`-f, --file <fichiers...>`	Fichier(s) spécifique(s)
`-c, --config <chemin>`	Chemin du fichier de configuration (.n8nlintrc.json)
`--disable-rule <nom>`	Désactiver une ou plusieurs règles spécifiques
`--list-rules`	Lister toutes les règles
`-o, --output <format>`	Format de sortie : text, json (par défaut : text)

Règles (11 règles) :

Règle	Sévérité	Description
`json-syntax`	erreur	Vérification de la syntaxe JSON
`required-fields`	erreur	Vérification des champs obligatoires (nom, nœuds, connexions)
`connection-reference`	erreur	Vérification de l'existence du nœud cible de la connexion
`webhook-id-required`	erreur	Vérifier que les nœuds webhook et formTrigger ont le champ webhookId
`orphaned-node`	avertissement	Détection des nœuds orphelins
`implicit-json-ref`	avertissement	Détection des références `$json` implicites
`expression-mode-prefix`	avertissement	Détection du préfixe `=` manquant
`ai-agent-output-ref`	avertissement	Détection des références erronées à la sortie de l'agent IA
`node-params`	avertissement	Validation du schéma des paramètres du nœud
`node-ref-field-check`	avertissement	Validation de l'existence du champ référencé
`node-ref-cardinality`	avertissement	Validation de l'utilisation de `.item`/`.first()`

Fichier de configuration (.n8nlintrc.json) :

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

Ordre de recherche du fichier de configuration :

Chemin spécifié avec l'option --config
.n8nlintrc.json / .n8nlintrc dans le répertoire cible
.n8nlintrc.json / .n8nlintrc dans le répertoire actuel

6. Formateur (Auto-formatage)

Remarque : fmt accepte des arguments positionnels pour les fichiers (pas d'option -f).

# Formater un fichier spécifique (argument positionnel)
./n8n-cli fmt definitions/<nom_fichier>

# Plusieurs fichiers
./n8n-cli fmt definitions/fichier1.yaml definitions/fichier2.yaml

# Formater un répertoire entier
./n8n-cli fmt -d ./definitions

# Aperçu uniquement
./n8n-cli fmt -d ./definitions --dry-run

7. Test (Exécution)

Tester les workflows via des webhooks de test :

# Test de base
./n8n-cli test <id-du-workflow>

# Avec des données de test
./n8n-cli test <id-du-workflow> -d '{"email": "[email protected]"}'

# Attendre la fin de l'exécution (recommandé)
./n8n-cli test <id-du-workflow> --wait-execution

# Activer automatiquement les workflows inactifs
./n8n-cli test <id-du-workflow> --activate

# Vérifier l'URL du webhook uniquement
./n8n-cli test <id-du-workflow> --dry-run

# Vérifier les paramètres d'entrée
./n8n-cli test <id-du-workflow> --show-inputs

Options :

Option	Description
`-d, --data <json>`	Données de test (chaîne JSON)
`--timeout <durée>`	Délai d'expiration HTTP (par défaut : 30s)
`--wait-execution`	Attendre la fin de l'exécution et afficher les résultats
`--activate`	Activer automatiquement les workflows inactifs
`--dry-run`	Vérifier l'URL du webhook uniquement
`--show-inputs`	Afficher les paramètres d'entrée
`-o, --output <fmt>`	Format de sortie : json, table (par défaut : json)

Test à partir d'un fichier local :

# Spécifier un fichier JSON/YAML local
./n8n-cli test ./definitions/mon-workflow.json

8. Exécution (Journaux et Erreurs)

Lister les exécutions récentes :

# Lister toutes les exécutions récentes
./n8n-cli execution list

# Format tableau pour une meilleure lisibilité
./n8n-cli -o table execution list

# Filtrer par statut
./n8n-cli execution list --status error
./n8n-cli execution list --status success

# Filtrer par workflow
./n8n-cli execution list --workflow <id-du-workflow>

# Limiter les résultats
./n8n-cli execution list --limit 5

# Filtres combinés
./n8n-cli execution list --workflow <id-du-workflow> --status error --limit 10

Obtenir les détails d'une exécution :

# Obtenir une exécution par son ID
./n8n-cli execution get <id-execution>

# Format tableau avec les détails des erreurs
./n8n-cli -o table execution get <id-execution>

# Inclure le résumé de l'exécution du nœud
./n8n-cli -o table execution get <id-execution> --show-data

Options pour execution list :

Option	Description
`-w, --workflow <id>`	Filtrer par ID du workflow
`-s, --status <statut>`	Filtrer par statut (success, error, running, waiting)
`-l, --limit <n>`	Nombre maximal d'exécutions (par défaut : 20)

Options pour execution get :

Option	Description
`--show-data`	Inclure le résumé de l'exécution du nœud dans la sortie

Informations d'erreur affichées :

Champ	Description
Nœud d'Erreur	Le nœud où l'erreur s'est produite
Message d'Erreur	Le message d'erreur
Détails de l'Erreur	Description supplémentaire de l'erreur (si disponible)
Dernier Nœud	Le dernier nœud exécuté

Flux de débogage typique :

# 1. Lister les erreurs récentes
./n8n-cli -o table execution list --status error --limit 5

# 2. Obtenir les détails d'une exécution spécifique ayant échoué
./n8n-cli -o table execution get <id-execution> --show-data

# 3. Examiner les détails de l'erreur et corriger le workflow

9. Convertir (Conversion de Format)

Convertir les fichiers de workflow entre les formats JSON et YAML (local uniquement, pas besoin d'API) :

# Convertir tous les workflows JSON en YAML
./n8n-cli convert -d ./definitions --format yaml

# Convertir des workflows spécifiques par ID
./n8n-cli convert -d ./definitions --format json --ids <id-du-workflow>

# Aperçu sans écrire
./n8n-cli convert -d ./definitions --format yaml --dry-run

# Conserver les fichiers originaux
./n8n-cli convert -d ./definitions --format yaml --keep

# Convertir un seul fichier
./n8n-cli convert --format yaml definitions/<nom_fichier>.json

Options :

Option	Description
`--format <format>`	Format cible : `json`, `yaml` (obligatoire)
`-d, --directory <répertoire>`	Répertoire à analyser pour les fichiers de workflow
`--ids <ids>`	IDs de workflow séparés par des virgules à convertir
`--tags <tags>`	Filtrer par balises (séparées par des virgules, condition ET)
`-t, --threshold <n>`	Nombre minimum de lignes pour l'externalisation du code (JSON→YAML)
`--dry-run`	Aperçu uniquement
`--keep`	Conserver les fichiers originaux

Comportement :

JSON→YAML : génère YAML + _subfiles/ avec le code externalisé
YAML→JSON : résout les références !include et supprime _subfiles/
Les fichiers déjà dans le format cible sont ignorés
Les fichiers originaux sont supprimés après la conversion, sauf si --keep

10. Tables de Données

Gérer les tables de données et les lignes :

# Lister toutes les tables de données
./n8n-...

[suite tronquée pour la traduction]

ubie-oss/n8n-cli

Qu'est-ce que n8n-cli ?

Demander à votre IA préférée

Documentation

Skill n8n-cli Operations

Initialisation de la Session (Important)

Priorité 1 : Construction depuis la Source Locale (Développement)

Priorité 2 : Mise à Jour Automatique depuis les Versions GitHub (Recommandé)

Solution de Repli : Construction depuis la Source

Configuration de l'Environnement

Vérification du Fichier .env

Création de .env (Uniquement si Nécessaire)

Commandes Courantes

1. Vérification de l'État du Workflow Distant

2. Importer des Workflows (Distant -> Local)

Vérifier le Format Local Avant l'Importation

3. Dry-run (Aperçu des Modifications)

4. Appliquer (Déploiement)

5. Linter (Contrôles de Qualité)

6. Formateur (Auto-formatage)

7. Test (Exécution)

8. Exécution (Journaux et Erreurs)

9. Convertir (Conversion de Format)

10. Tables de Données

Skills associés

steipete/notion

langchain-ai/langchain

bytedance/podcast-generation

composiohq/twitter-algorithm-optimizer

composiohq/competitive-ads-extractor

upstash/context7