Habilidade de Operações do n8n-cli

Uma habilidade para auxiliar no gerenciamento de workflows usando o n8n-cli (TypeScript/Bun).

Inicialização da Sessão (Importante)

Para novas sessões, sempre execute o seguinte primeiro para garantir que o n8n-cli esteja atualizado.

Prioridade 1: Construir a partir da Fonte Local (Desenvolvimento)

Se o repositório fonte do n8n-cli estiver disponível via add-dir (por exemplo, /caminho/para/n8n-cli/Makefile existe), construa a partir da fonte local em vez de usar uma versão pré-compilada. Isso garante que as últimas alterações de desenvolvimento sejam refletidas imediatamente.

# Se o repositório n8n-cli estiver visível via add-dir
N8N_CLI_REPO="/caminho/para/n8n-cli"  # Substitua pelo caminho do add-dir
if [ -f "$N8N_CLI_REPO/Makefile" ]; then
  echo "Construindo n8n-cli a partir da fonte local: $N8N_CLI_REPO"
  cd "$N8N_CLI_REPO" && bun install && make build
  cp "$N8N_CLI_REPO/n8n-cli" /caminho/para/destino/n8n-cli
  cd /caminho/para/destino
  echo "Construído a partir da fonte local: $(./n8n-cli version 2>/dev/null | head -1)"
fi

Prioridade 2: Atualização Automática a partir de GitHub Releases (Preferido)

Binários pré-compilados estão disponíveis no GitHub Releases. Isso é mais rápido do que compilar a partir do código fonte e garante que você esteja executando a versão oficial.

# 1. Verifique a versão do último release
LATEST_TAG=$(gh release view --repo ubie-oss/n8n-cli --json tagName -q '.tagName' 2>/dev/null)

# 2. Verifique a versão local atual (se o binário existir)
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. Compare e baixe se necessário
if [ -z "$CURRENT_VERSION" ] || [ "$CURRENT_VERSION" != "$LATEST_TAG" ]; then
  echo "Atualizando n8n-cli: ${CURRENT_VERSION:-nenhuma} -> ${LATEST_TAG}"

  # Detecta 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 "Arquitetura não suportada: $ARCH"; exit 1 ;;
  esac

  # Baixa o binário
  gh release download "$LATEST_TAG" --repo ubie-oss/n8n-cli --pattern "$ASSET_NAME" --output n8n-cli --clobber
  chmod +x ./n8n-cli
  echo "Atualizado para $(./n8n-cli version 2>/dev/null | head -1)"
else
  echo "n8n-cli está atualizado: $CURRENT_VERSION"
fi

Plano B: Construir a partir do Código Fonte

Se a CLI gh não estiver disponível ou você precisar de uma versão de desenvolvimento:

# Instalar dependências + construir CLI
bun install && make build

Verificação da construção:

./n8n-cli version

Configuração do Ambiente

Verificando o Arquivo .env

Se .env existir na raiz do projeto, o n8n-cli pode ser usado sem especificar parâmetros. Não leia o conteúdo.

# Apenas verifique a existência do .env (não leia o conteúdo)
test -f .env && echo ".env existe - n8n-cli pode ser usado sem parâmetros"

Se .env existir:

N8N_API_URL e N8N_API_KEY já estão configurados
./n8n-cli pode ser executado sem parâmetros

Se .env não existir:

Peça ao usuário para criar um arquivo .env
Ou use as flags --api-url e --api-key

Criando .env (Apenas se Necessário)

cp .env.example .env
# Peça ao usuário para editar

Comandos Comuns

1. Verificando o Status de Workflows Remotos

Verificar um workflow específico:

# Obter informações do workflow por ID
./n8n-cli workflow get <workflow-id>

# Exibir em formato de tabela para legibilidade
./n8n-cli -o table workflow get <workflow-id>

# Salvar em arquivo (útil para comparação de diff)
./n8n-cli workflow get <workflow-id> > /tmp/remote-workflow.json

Listar workflows:

# Todos os workflows
./n8n-cli workflow list

# Formato de tabela
./n8n-cli -o table workflow list

# Apenas ativos
./n8n-cli workflow list --active

2. Importar Workflows (Remoto -> Local)

Verificar o Formato Local Antes de Importar

Ao puxar conteúdo remoto para local, siga sempre estes passos:

Verifique o formato do arquivo local

# Verifique se o arquivo existe e seu formato
ls -la definitions/*<workflow-id>* definitions/**/*<workflow-id>*

Use as opções de importação apropriadas com base no formato
- Arquivos .json: use apenas --ids
- Arquivos .yaml/.yml: use tanto --ids quanto --yaml

Importar um workflow específico:

# Workflow em formato JSON
./n8n-cli import --ids=<workflow-id>

# Workflow em formato YAML
./n8n-cli import --ids=<workflow-id> --yaml

# Para um diretório personalizado
./n8n-cli import --ids=<workflow-id> -d ./meu-dir

Importar múltiplos workflows:

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

Importar todos os workflows:

./n8n-cli import

Opções adicionais:

Opção	Descrição
`--include-archived`	Incluir workflows arquivados
`--cleanup-orphans`	Excluir arquivos órfãos sem IDs correspondentes
`-t, --threshold <int>`	Linhas mínimas para extração de arquivo externo (padrão: 0, configurável em CLAUDE.md)
`--dry-run`	Apenas pré-visualização (sem alterações em arquivos)
`--tags <tags>`	Filtrar por nomes de tags separados por vírgulas (condição AND)

3. Dry-run (Pré-visualização de Alterações)

Sempre verifique com dry-run antes de aplicar:

# Pré-visualizar alterações para todos os workflows
./n8n-cli apply --dry-run

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

# Apenas arquivo específico
./n8n-cli apply --dry-run -d definitions/caminho/para/workflow.json

Exemplo de saída:

=== CREATE (1 workflow) ===
  + novo-workflow.json (nome: "Nova Automação")

=== UPDATE (2 workflows) ===
  ~ existente.json (id: R2cTI0LDzCJSnvNG)
    - nome: "Nome Antigo" -> "Novo Nome"
    - nodes: 3 -> 5 nodes

=== SKIP (1 workflow) ===
  = inalterado.json (sem alterações)

Resumo (dry-run): 1 para criar, 2 para atualizar, 1 inalterado

4. Apply (Implantar)

Assistentes de IA devem sempre usar --ids

# Aplicar apenas workflow específico (recomendado)
./n8n-cli apply --ids=<workflow-id>

# Aplicar apenas um arquivo específico
./n8n-cli apply -d definitions/caminho/para/workflow.json

# Forçar apply (sobrescrever alterações remotas)
./n8n-cli apply --ids=<workflow-id> --force

Proibido: Aplicar em um diretório inteiro

# Estes NÃO devem ser executados por IA
./n8n-cli apply -d definitions/
./n8n-cli apply

Opções adicionais:

Opção	Descrição
`--from-git-changes <spec>`	Aplicar apenas arquivos alterados no diff do Git
`--yaml` / `--no-yaml`	Ativar/desativar processamento YAML
`--allow-duplicates`	Pular a verificação de nome duplicado upstream (padrão: ativado; use `--force` para ignorar avisos em vez de desativar a verificação)
`--no-auto-tag`	Desativar etiquetagem automática (managed-as-code)
`-p, --project <id>`	Especificar ID do projeto alvo

Variáveis de ambiente:

APPLY_FILTER_BY_TAGS - Filtrar por nomes de tags separados por vírgulas (condição AND)

Modo Git diff:

# Aplicar apenas alterações de uma branch de funcionalidade
./n8n-cli apply --from-git-changes origin/main..HEAD

# Pré-visualização
./n8n-cli apply --from-git-changes origin/main..HEAD --dry-run

# Alterações dos últimos 3 commits
./n8n-cli apply --from-git-changes HEAD~3..HEAD

Detecção de conflito 3-way: Quando --from-git-changes é especificado, os conflitos são detectados comparando Base (ponto de referência), Local (atual) e Remoto (servidor) para identificar apenas conflitos verdadeiros.

5. Linter (Verificações de Qualidade)

O linter está integrado ao CLI. Nenhuma compilação separada é necessária.

Nota: Argumentos posicionais não são suportados. Sempre especifique arquivos/diretórios com -f ou -d.

# Verificar um arquivo específico (-f obrigatório)
./n8n-cli lint -f definitions/<nome-do-arquivo>

# Verificar um diretório específico
./n8n-cli lint -d ./definitions/exemplo-projeto

# Verificar todos os workflows
./n8n-cli lint -d ./definitions

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

Opções:

Opção	Descrição
`-d, --dir <caminho>`	Diretório de arquivos de definição
`-f, --file <arquivos...>`	Arquivo(s) específico(s)
`-c, --config <caminho>`	Caminho do arquivo de configuração (.n8nlintrc.json)
`--disable-rule <nome>`	Desativar regra(s) específica(s)
`--list-rules`	Listar todas as regras
`-o, --output <formato>`	Formato de saída: text, json (padrão: text)

Regras (11 regras):

Regra	Severidade	Descrição
`json-syntax`	erro	Verificação de sintaxe JSON
`required-fields`	erro	Verificação de campos obrigatórios (name, nodes, connections)
`connection-reference`	erro	Verificação de existência do nó alvo da conexão
`webhook-id-required`	erro	Verificar se nós webhook e formTrigger têm o campo webhookId
`orphaned-node`	aviso	Detecção de nós órfãos
`implicit-json-ref`	aviso	Detecção de referência implícita a `$json`
`expression-mode-prefix`	aviso	Detecção de prefixo `=` ausente
`ai-agent-output-ref`	aviso	Detecção de referência incorreta à saída do Agente de IA
`node-params`	aviso	Validação de esquema de parâmetros do nó
`node-ref-field-check`	aviso	Validação de existência de campo referenciado
`node-ref-cardinality`	aviso	Validação de uso de `.item`/`.first()`

Arquivo de configuração (.n8nlintrc.json):

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

Ordem de pesquisa do arquivo de configuração:

Caminho especificado com a flag --config
.n8nlintrc.json / .n8nlintrc no diretório alvo
.n8nlintrc.json / .n8nlintrc no diretório atual

6. Formatador (Auto-formatação)

Nota: fmt aceita argumentos posicionais para arquivos (sem opção -f).

# Formatar um arquivo específico (argumento posicional)
./n8n-cli fmt definitions/<nome-do-arquivo>

# Múltiplos arquivos
./n8n-cli fmt definitions/arquivo1.yaml definitions/arquivo2.yaml

# Formatar um diretório inteiro
./n8n-cli fmt -d ./definitions

# Apenas pré-visualização
./n8n-cli fmt -d ./definitions --dry-run

7. Teste (Execução)

Testar workflows via webhooks de teste:

# Teste básico
./n8n-cli test <workflow-id>

# Com dados de teste
./n8n-cli test <workflow-id> -d '{"email": "[email protected]"}'

# Aguardar a conclusão da execução (recomendado)
./n8n-cli test <workflow-id> --wait-execution

# Auto-ativar workflows inativos
./n8n-cli test <workflow-id> --activate

# Verificar apenas URL do webhook
./n8n-cli test <workflow-id> --dry-run

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

Opções:

Opção	Descrição
`-d, --data <json>`	Dados de teste (string JSON)
`--timeout <duração>`	Timeout HTTP (padrão: 30s)
`--wait-execution`	Aguardar a conclusão da execução e mostrar resultados
`--activate`	Auto-ativar workflows inativos
`--dry-run`	Verificar apenas URL do webhook
`--show-inputs`	Exibir parâmetros de entrada
`-o, --output <fmt>`	Formato de saída: json, table (padrão: json)

Testar a partir de um arquivo local:

# Especificar um arquivo JSON/YAML local
./n8n-cli test ./definitions/meu-workflow.json

8. Execução (Logs e Erros)

Listar execuções recentes:

# Listar todas as execuções recentes
./n8n-cli execution list

# Formato de tabela para legibilidade
./n8n-cli -o table execution list

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

# Filtrar por workflow
./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

Obter detalhes da execução:

# Obter execução por ID
./n8n-cli execution get <execution-id>

# Formato de tabela com detalhes do erro
./n8n-cli -o table execution get <execution-id>

# Incluir resumo de execução dos nós
./n8n-cli -o table execution get <execution-id> --show-data

Opções para execution list:

Opção	Descrição
`-w, --workflow <id>`	Filtrar por ID do workflow
`-s, --status <status>`	Filtrar por status (success, error, running, waiting)
`-l, --limit <n>`	Número máximo de execuções (padrão: 20)

Opções para execution get:

Opção	Descrição
`--show-data`	Incluir resumo de execução dos nós na saída

Informações de erro exibidas:

Campo	Descrição
Error Node	O nó onde o erro ocorreu
Error Message	A mensagem de erro
Error Details	Descrição adicional do erro (se disponível)
Last Node	O último nó executado

Fluxo de trabalho típico de depuração:

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

# 2. Obter detalhes de uma execução com falha específica
./n8n-cli -o table execution get <execution-id> --show-data

# 3. Revisar detalhes do erro e corrigir o workflow

9. Converter (Conversão de Formato)

Converter arquivos de workflow entre formatos JSON e YAML (apenas local, sem necessidade de API):

# Converter todos os workflows JSON para YAML
./n8n-cli convert -d ./definitions --format yaml

# Converter workflows específicos por ID
./n8n-cli convert -d ./definitions --format json --ids <workflow-id>

# Pré-visualização sem escrever
./n8n-cli convert -d ./definitions --format yaml --dry-run

# Manter arquivos originais
./n8n-cli convert -d ./definitions --format yaml --keep

# Converter um único arquivo
./n8n-cli convert --format yaml definitions/<nome-do-arquivo>.json

Opções:

Opção	Descrição
`--format <formato>`	Formato alvo: `json`, `yaml` (obrigatório)
`-d, --directory <dir>`	Diretório para procurar arquivos de workflow
`--ids <ids>`	IDs de workflow separados por vírgulas para converter
`--tags <tags>`	Filtrar por tags (separadas por vírgulas, condição AND)
`-t, --threshold <n>`	Linhas mínimas para externalização de código (JSON→YAML)
`--dry-run`	Apenas pré-visualização
`--keep`	Manter arquivos originais

Comportamento:

JSON→YAML: gera YAML + _subfiles/ com código externalizado
YAML→JSON: resolve referências !include e remove _subfiles/
Arquivos já no formato alvo são ignorados
Arquivos originais removidos após a conversão, a menos que --keep

10. Tabelas de Dados

Gerenciar tabelas de dados e linhas:

# Listar todas as tabelas de dados
./n8n-cli data-table list

# Formato de tabela
./n8n-cli -o table data-table list

# Obter detalhes de uma tabela
./n8n-cli data-table get <table-id>

# Listar linhas de uma tabela
./n8n-cli data-table list-rows <table-id>

# Apagar uma tabela
./n8n-cli data-table delete <table-id>

# Forçar apagar (sem confirmação)
./n8n-cli data-table delete <table-id> --force

Opções:

Opção	Descrição
`-o, --output <formato>`	Formato de saída (json, table; padrão: json)
`--raw`	Saída bruta da API (sem processamento de status)

11. Utilitário (Auditoria de Nó)

Verificar quais workflows usam um tipo específico de nó:

# Encontrar workflows que usam um tipo de nó
./n8n-cli util node-usage <node-type>

# Formato de tabela
./n8n-cli -o table util node-usage <node-type>

# Exemplos
./n8n-cli util node-usage n8n-nodes-base.httpRequest
./n8n-cli util node-usage n8n-nodes-base.webhook
./n8n-cli -o table util node-usage n8n-nodes-base.set

Opções:

Opção	Descrição
`-d, --dir <caminho>`	Caminho do diretório de definições (padrão: ./definitions)
`-g, --global`	Pesquisar em todos os arquivos .json/.yaml no diretório de definições
`-i, --input`	Pesquisar por tipo de nó em entradas em vez de tipo

Comportamento:

Pesquisa arquivos de definição no diretório especificado
Retorna nomes de arquivo e nomes de workflow onde o tipo de nó é encontrado
Útil para auditoria de dependências e análise de impacto

Guia de Referência Rápida de Comandos

Comando	Descrição	Uso Comum
`workflow get`	Obter detalhes do workflow remoto	`./n8n-cli workflow get <id>`
`workflow list`	Listar workflows remotos	`./n8n-cli -o table workflow list`
`import`	Puxar workflows remotos para local	`./n8n-cli import --ids=<id>`
`apply`	Enviar workflows locais para remoto	`./n8n-cli apply --ids=<id> --dry-run`
`lint`	Verificar qualidade dos arquivos de definição	`./n8n-cli lint -d ./definitions`
`fmt`	Auto-formatar arquivos de definição	`./n8n-cli fmt definitions/*.yaml`
`test`	Testar workflow via webhook	`./n8n-cli test <id> --wait-execution`
`execution list`	Listar execuções recentes	`./n8n-cli -o table execution list --status error`
`execution get`	Obter detalhes de execução	`./n8n-cli -o table execution get <id>`
`convert`	Converter entre formatos JSON/YAML	`./n8n-cli convert -d . --format yaml`
`data-table`	Gerenciar tabelas de dados	`./n8n-cli data-table list`
`util node-usage`	Auditar uso de tipos de nó	`./n8n-cli util node-usage <tipo>`

Variáveis de Ambiente

Nome	Descrição
`N8N_API_URL`	URL base da API n8n (ex: https://instancia-n8n.exemplo.com/api/v1)
`N8N_API_KEY`	Chave de API para autenticação
`APPLY_FILTER_BY_TAGS`	Filtrar workflows a serem aplicados por tags (condição AND)

Resolução de Problemas

Aplicação:

Workflow não encontrado: Verifique o ID do workflow ou o caminho do arquivo
Erro de autenticação: Verifique N8N_API_URL e N8N_API_KEY no .env
Tag de erro: Se apply --ids ou deploy --ids falhar com "unable to tag", configure --no-auto-tag

Linter:

Saída estranha da CLI: O n8n-cli usa Node.js; vs. Bun mostra saída stderr adicional. Use 2>/dev/null se precisar de saída limpa, ou use o modo -o json que produz JSON válido para stdout
Posicional vs. Flag: lint requer -f <arquivo>; fmt usa argumentos posicionais (fmt <arquivo>)

Teste:

Execução em andamento: Use --wait-execution para aguardar a conclusão
Workflows inativos: Use --activate para ativá-los automaticamente antes do teste

Arquivos de Definição:

Workflows não encontrados pelo import: Verifique a estrutura do diretório definitions/
Entrada com nome inválido: Verifique se o nome não contém caracteres especiais não suportados pelo sistema de arquivos

Segurança e Boas Práticas

Nunca leia ou exiba valores de N8N_API_KEY ou tokens de autenticação
Sempre use --ids ao aplicar/implantar para evitar atualizações acidentais em massa
Use --dry-run antes de apply para revisar alterações
Prefira --from-git-changes para implantações controladas por versão
Use --no-auto-tag se você gerencia tags manualmente

Construção de Desenvolvimento

# Clonar o repositório
git clone https://github.com/ubie-oss/n8n-cli.git
cd n8n-cli

# Instalar dependências (usa Bun)
bun install

# Construir o binário
make build

# O binário está em ./n8n-cli

Pré-requisitos:

Bun (runtime JavaScript)
Make

Informações de Licenciamento

Este software contém código modificado de n8n (n8n-io/n8n), usado sob a Licença Pública Sustentável enquanto aplicável. Os componentes modificados são claramente indicados nos cabeçalhos dos arquivos de origem.

Perguntar na sua IA favorita

Documentação

Habilidade de Operações do n8n-cli

Inicialização da Sessão (Importante)

Prioridade 1: Construir a partir da Fonte Local (Desenvolvimento)

Prioridade 2: Atualização Automática a partir de GitHub Releases (Preferido)

Plano B: Construir a partir do Código Fonte

Configuração do Ambiente

Verificando o Arquivo .env

Criando .env (Apenas se Necessário)

Comandos Comuns

1. Verificando o Status de Workflows Remotos

2. Importar Workflows (Remoto -> Local)

Verificar o Formato Local Antes de Importar

3. Dry-run (Pré-visualização de Alterações)

4. Apply (Implantar)

5. Linter (Verificações de Qualidade)

6. Formatador (Auto-formatação)

7. Teste (Execução)

8. Execução (Logs e Erros)

9. Converter (Conversão de Formato)

10. Tabelas de Dados

11. Utilitário (Auditoria de Nó)

Guia de Referência Rápida de Comandos

Variáveis de Ambiente

Resolução de Problemas

Aplicação:

Linter:

Teste:

Arquivos de Definição:

Segurança e Boas Práticas

Construção de Desenvolvimento

Informações de Licenciamento

Habilidades Relacionadas

steipete/notion

langchain-ai/langchain

bytedance/podcast-generation

composiohq/twitter-algorithm-optimizer

composiohq/competitive-ads-extractor

upstash/context7