pokgak/n8n

n8n Skill - Manage Workflows and Executions

n8n Concepts

Workflows

A workflow is an automation that connects multiple services/apps. It consists of:

• Nodes - Individual steps that perform actions (HTTP requests, code execution, integrations)
• Connections - Links between nodes defining data flow
• Triggers - How the workflow starts (webhook, schedule, manual, etc.)

Node Types

• Trigger nodes - Start workflows (Webhook, Schedule, Manual)
• Regular nodes - Process data (HTTP Request, Set, IF, Switch)
• Code nodes - Custom JavaScript/Python logic
• Integration nodes - Connect to services (Slack, Discord, Notion, etc.)

Executions

An execution is a single run of a workflow. States:

• success - Completed without errors
• error - Failed at some node
• running - Currently executing
• waiting - Paused, waiting for external event
• canceled - Manually stopped

Execution Modes

• webhook - Triggered by HTTP request
• trigger - Triggered by schedule or event
• manual - Triggered manually from UI
• retry - Retried from a failed execution

Webhooks

HTTP endpoints that trigger workflows:

• Production webhook - /webhook/<path> - Always active when workflow is active
• Test webhook - /webhook-test/<path> - For testing, shows data in UI

Credentials

Stored authentication for services (API keys, OAuth tokens). Referenced by nodes but not exposed in workflow JSON.

CLI Setup

The CLI is available via uvx (no installation needed):

uvx n8n-client --help

Or install via pip/uv:

pip install n8n-client
# or
uv pip install n8n-client

Environment Variables

Required:

• N8N_API_KEY - API key from n8n (Settings → n8n API)
• N8N_BASE_URL - n8n instance URL (e.g., https://your-instance.app.n8n.cloud)

CLI Reference

List Workflows

# List all workflows
uvx n8n-client workflows

# Active workflows only
uvx n8n-client workflows --active

# JSON output
uvx n8n-client workflows --json

Workflow Details

# Get workflow details
uvx n8n-client workflow <workflow_id>

# Full JSON output
uvx n8n-client workflow <workflow_id> --json

Activate/Deactivate Workflows

uvx n8n-client activate <workflow_id>
uvx n8n-client deactivate <workflow_id>

List Nodes in Workflow

# List all nodes (Code nodes marked with *)
uvx n8n-client nodes <workflow_id>

View/Edit Nodes

# View node details
uvx n8n-client node <workflow_id> "node name"

# View Code node's JavaScript
uvx n8n-client node <workflow_id> "node name" --code

# Update Code node from file
uvx n8n-client node <workflow_id> "node name" --set-code script.js

# Rename a node
uvx n8n-client node <workflow_id> "old name" --rename "new name"

# Set node parameter (supports dot notation for nested keys)
uvx n8n-client node <workflow_id> "HTTP Request" --set-param url="https://api.example.com"
uvx n8n-client node <workflow_id> "Agent" --set-param options.systemMessage="You are helpful"

# Set multiple parameters at once
uvx n8n-client node <workflow_id> "Node" -p timeout=5000 -p retries=3

# Bulk update parameters from JSON (deep merged)
uvx n8n-client node <workflow_id> "Node" --set-param-json '{"options": {"systemMessage": "Hello"}}'

Export/Import Code Nodes

Useful for editing Code node scripts in a proper editor:

# Export all Code nodes to files
uvx n8n-client export-code <workflow_id> ./nodes/

# Import updated scripts back
uvx n8n-client import-code <workflow_id> ./nodes/

Trigger Workflows

# Trigger workflow by name via webhook
uvx n8n-client trigger "Workflow Name"

# With JSON payload
uvx n8n-client trigger "Workflow Name" --data '{"key": "value"}'

# With payload from file
uvx n8n-client trigger "Workflow Name" --file payload.json

# Use test webhook URL
uvx n8n-client trigger "Workflow Name" --test

List Executions

# Recent executions
uvx n8n-client executions

# Filter by workflow
uvx n8n-client executions --workflow <workflow_id>

# Filter by status (error, success, running, waiting, canceled)
uvx n8n-client executions --status error

# Limit results
uvx n8n-client executions -n 100

Execution Details

# Get execution details (shows error info for failed executions)
uvx n8n-client execution <execution_id>

# Include full execution data
uvx n8n-client execution <execution_id> --data

# JSON output
uvx n8n-client execution <execution_id> --data --json

Retry Failed Execution

uvx n8n-client retry <execution_id>

# Use latest workflow version
uvx n8n-client retry <execution_id> --latest

Credentials Management

Note: The n8n API does not allow reading credential values (security restriction). You can only list credentials metadata, create new credentials, and delete credentials. To update a credential, you must delete and recreate it.

# List all credentials (metadata only - id, name, type)
uvx n8n-client credentials

# Get schema for a credential type (shows required fields)
uvx n8n-client credential-schema httpHeaderAuth
uvx n8n-client credential-schema openAiApi --json

# Create a credential
uvx n8n-client create-credential --name "My API Key" --type httpHeaderAuth --data '{"name": "X-API-Key", "value": "secret"}'

# Create from file
uvx n8n-client create-credential --name "OpenAI" --type openAiApi --data-file credentials.json

# Delete a credential
uvx n8n-client delete-credential <credential_id>

Common Workflows

Troubleshoot Failed Executions

# 1. Find failed executions
uvx n8n-client executions --status error

# 2. Get error details
uvx n8n-client execution <id>

# 3. Get full data for debugging
uvx n8n-client execution <id> --data --json

Edit Code Nodes

# 1. Export all Code nodes
uvx n8n-client export-code <workflow_id> ./nodes/

# 2. Edit scripts in your editor
# Files: ./nodes/node_name.js

# 3. Import changes back
uvx n8n-client import-code <workflow_id> ./nodes/

Quick Node Update

# View current code
uvx n8n-client node <workflow_id> "node name" --code > script.js

# Edit script.js...

# Update node
uvx n8n-client node <workflow_id> "node name" --set-code script.js

Test Webhook Workflow

# Trigger with test payload
uvx n8n-client trigger "Workflow Name" --test --file test_payload.json

# Check execution result
uvx n8n-client executions --workflow <id> -n 1

Execution Data Structure

When debugging with --data --json, the execution contains:

execution
├── id                    # Execution ID
├── status                # success, error, running, etc.
├── mode                  # webhook, trigger, manual, retry
├── startedAt / stoppedAt # Timestamps
├── workflowData          # Snapshot of workflow at execution time
│   ├── name
│   ├── nodes[]
│   └── connections
└── data
    └── resultData
        ├── runData       # Output from each node
        │   └── [nodeName][]
        │       ├── data.main[][] # Node output items
        │       └── executionStatus
        ├── lastNodeExecuted
        └── error         # If failed
            ├── message
            ├── description
            └── node      # Which node failed

Common Error Patterns

Webhook Payload Issues

• Check execution --data --json and look at the Webhook node's output
• Payload is in runData.Webhook[0].data.main[0][0].json.body

Code Node Errors

• Error message shows the JavaScript error
• Use node <workflow_id> "node name" --code to view the code
• Common: undefined variables, JSON parsing, missing fields

Integration Failures

• Usually credential or API issues
• Check if the service is accessible
• Verify credential permissions