leadgrow-n8n-cli

The most comprehensive n8n CLI ever built. No other n8n CLI comes close.

85+ commands. 100% REST API coverage. GitOps. Clay integration. Workflow templates. Zero-trust webhooks. MCP server. Built for AI agents and humans alike.

| Feature | leadgrow-n8n-cli | n8n-cli (edenreich) | n8n-agent-cli (bcharleson) | n8n-mcp (czlonkowski) | |---------|:---:|:---:|:---:|:---:| | Commands | 85+ | 15 | 15 | MCP only | | API Coverage | 100% | ~20% | ~20% | ~60% | | GitOps (sync/refresh/prune) | Yes | Yes | No | No | | Clay Integration | Yes | No | No | No | | Workflow Templates | Yes | No | 2 | No | | Template Engine | Yes | No | No | No | | Compound Tools (health-check, overview, search) | Yes | No | No | No | | Built-in docs Reference | Yes | No | No | No | | Setup Wizard | Yes | No | No | No | | MCP Server | Yes | No | Yes | Yes | | Structured Errors | Yes | No | No | No | | Multi-Instance Profiles | Yes | Env vars | Basic | No | | Shell Completions | Yes | Yes | No | No | | Zero-Trust Webhooks | Yes | No | Yes | No | | --json Flag | Yes | JSON flag | No | N/A | | Claude Code Skill | Yes | No | No | No |

Quick Start

# Install globally
npm install -g leadgrow-n8n-cli

# Interactive setup (saves config + configures MCP for Claude/Cursor)
n8n-cli setup

# Or non-interactive
n8n-cli setup --api-key YOUR_KEY --url https://your-n8n.example.com --skip-mcp

First Commands

# Check connection
n8n-cli auth status --json

# Full instance snapshot in one call
n8n-cli instance overview --json

# List all workflows
n8n-cli workflows list --json

# Health report for a specific workflow
n8n-cli workflows health-check <workflow-id> --json

# Find workflows by name, tags, or node types
n8n-cli workflows search "keyword" --json

# Find recent errors
n8n-cli executions list --status error --limit 10 --json

# Retry a failed execution
n8n-cli executions retry <execution-id> --json

Full Reference

# 921-line structured reference — everything in one place
n8n-cli docs

# Just workflow commands
n8n-cli docs workflows

# Clay integration patterns
n8n-cli docs clay

# Available workflow templates
n8n-cli docs templates

Features

100% n8n REST API Coverage (85+ Commands)

Every endpoint in the n8n public API, organized into 15 command groups:

| Group | Commands | Description | |-------|----------|-------------| | workflows | 15 | List, get, create, update, delete, activate, deactivate, archive, unarchive, transfer, history, tags get/set, sync, refresh | | executions | 8 | List, get, delete, retry, stop, stop-all, tags get/set | | credentials | 6 | List, create, update, delete, schema, transfer | | tags | 5 | List, create, get, update, delete | | users | 5 | List, create, get, delete, role | | variables | 4 | List, create, update, delete | | projects | 8 | List, create, update, delete, users list/add/remove/role | | data-tables | 10 | List, create, get, update, delete, rows list/insert/update/upsert/delete | | community-packages | 4 | List, install, update, uninstall | | webhooks | 2 | Trigger, test (zero-trust pattern) | | instance | 4 | Connect, health, discover, overview | | audit | 1 | Generate security audit | | source-control | 1 | Pull from git | | auth | 3 | Status, login, logout | | config | 4 | Show, set, reset, path |

Plus 5 compound commands: instance overview, workflows health-check, workflows search, workflows validate, workflows from-template

Plus meta commands: setup, docs, mcp, completions

GitOps Workflow Management

Version-control your n8n workflows in Git:

# Pull ALL remote workflows to local JSON files
n8n-cli workflows refresh --dir ./workflows --all --json

# Preview what would change before pushing
n8n-cli workflows sync --dir ./workflows --dry-run --json

# Push local changes to n8n
n8n-cli workflows sync --dir ./workflows --json

# Push + delete remote workflows not in local files
n8n-cli workflows sync --dir ./workflows --prune --json

Features:

• Change detection (content, activation state, tags)
• Auto-creates missing tags during sync
• Dry-run mode for safe previews
• JSON and YAML file support
• Prune mode for clean sync

Clay Integration (GTM Game-Changer)

Pre-built n8n workflow templates that combine HTTP Request nodes with Clay's API for lead enrichment pipelines:

# See Clay integration patterns
n8n-cli docs clay

# Deploy a Clay lead enrichment pipeline
n8n-cli workflows from-template --template clay-lead-enrichment \
  --var clay_webhook_id=wh_abc123 \
  --var clay_table_id=t_xyz789 \
  --var clay_session_token=sess_xxx \
  --var wait_minutes=10 \
  --deploy --json

# Preview without deploying
n8n-cli workflows from-template --template clay-lead-enrichment \
  --var clay_webhook_id=wh_abc123 \
  --dry-run --json

Available Templates:

| Template | Description | |----------|-------------| | clay-lead-enrichment | Webhook -> Clay push -> Wait -> Query enriched results -> Respond | | error-notifier | Error Trigger -> Format -> Telegram notification | | webhook-to-slack | Webhook -> Format -> Slack post |

Workflow Templates & Engine

Deploy workflows from templates with variable substitution:

# List available templates
n8n-cli docs templates

# Preview generated workflow
n8n-cli workflows from-template --template error-notifier \
  --var telegram_chat_id=-100123456 \
  --var telegram_credential_id=8VWS2lf \
  --dry-run --json

# Deploy directly to n8n
n8n-cli workflows from-template --template error-notifier \
  --var telegram_chat_id=-100123456 \
  --var telegram_credential_id=8VWS2lf \
  --deploy --json

# Validate a workflow file before deploying
n8n-cli workflows validate --file ./my-workflow.json --json

Compound Commands (One Call, Full Picture)

Commands that aggregate multiple API calls into a single, actionable response:

# Full instance snapshot: workflow counts, tags, recent errors
n8n-cli instance overview --json

# Workflow health: execution count, error rate, recommendation
n8n-cli workflows health-check <id> --json

# Fuzzy search across names, tags, and node types
n8n-cli workflows search "bison" --json

# Pre-deployment validation
n8n-cli workflows validate --file ./workflow.json --json

Zero-Trust Webhooks

Trigger n8n workflows via webhooks without exposing API keys. n8n handles credentials internally:

# Fire a production webhook
n8n-cli webhooks trigger \
  --url "https://your-n8n.example.com/webhook/abc-123" \
  --payload '{"email":"[email protected]","action":"enrich"}' \
  --json

# Fire a test webhook (workflow must be open in editor)
n8n-cli webhooks test \
  --url "https://your-n8n.example.com/webhook-test/abc-123" \
  --payload '{"test":true}' \
  --json

Multi-Instance Profiles

Manage multiple n8n instances (dev, staging, production):

# Connect instances
n8n-cli setup --api-key KEY1 --url https://dev.n8n.example.com --profile dev
n8n-cli setup --api-key KEY2 --url https://prod.n8n.example.com --profile prod

# Switch between them
n8n-cli workflows list --profile dev --json
n8n-cli workflows list --profile prod --json

# View saved profiles
n8n-cli config show --json

Setup Wizard

Interactive setup like the best CLI tools (inspired by bison-cli):

n8n-cli setup

  n8n-cli  v1.0.0
  Comprehensive n8n CLI + MCP server

  Step 1/3 - API Key
  ---------------------------------------------------
  > API key: ****

  Step 2/3 - Instance URL
  ---------------------------------------------------
  > n8n instance URL (http://localhost:5678):

  Verifying connection...
  + Connected successfully! (n8n 1.x.x)
  + Config saved to ~/.n8n-cli/config.json

  Step 3/3 - AI Integration (MCP)
  ---------------------------------------------------
  + Claude Desktop
  + Claude Code
  + Cursor

  +----------------------------------------------+
  |  Setup complete!                             |
  |                                              |
  |  Next steps:                                 |
  |    n8n-cli workflows list                    |
  |    n8n-cli executions list --status error    |
  |    n8n-cli workflows sync --dir ./workflows  |
  |    n8n-cli auth status                       |
  +----------------------------------------------+

Structured Errors

Every error returns machine-readable JSON with recovery guidance:

{
  "error": "not_found",
  "message": "Workflow 'xyz' not found",
  "suggestion": "Run 'n8n-cli workflows list --json' to find valid IDs",
  "retryable": false
}

Semantic exit codes: 0 success, 2 validation, 3 not found, 4 auth/permission, 5 version incompatible.

MCP Server

Exposes all commands as MCP tools for Claude Desktop, Cursor, and other AI environments:

# Start MCP server (stdio transport)
n8n-cli mcp

Add to Claude Desktop config:

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["leadgrow-n8n-cli", "mcp"]
    }
  }
}

Shell Completions

# Bash
source <(n8n-cli completions bash)

# Zsh
source <(n8n-cli completions zsh)

# Fish
n8n-cli completions fish | source

Global Flags

--profile <name>     Instance profile (default: "default")
--url <url>          Override instance URL
--api-key <key>      Override API key
-o, --output <fmt>   table | json | yaml
--json               Shorthand for --output json
--quiet              Suppress output
--debug              Debug logging
--no-color           Disable colored output

Self-Hosted n8n Compatibility

Works with any n8n instance — self-hosted or cloud. Some features depend on your n8n version:

| Feature | Community (Free) | Enterprise | |---------|:---:|:---:| | Workflows, Executions, Tags | Yes | Yes | | Credentials (create/update/delete) | Yes | Yes | | Credentials (list) | n8n 0.220+ | Yes | | Users | Yes | Yes | | Variables | No | Yes | | Projects | No | Yes | | Source Control | No | Yes | | Audit | No | Yes | | Data Tables | n8n 1.60+ | n8n 1.60+ | | Community Packages | n8n 1.50+ | n8n 1.50+ | | Workflow Archive/Unarchive | n8n 1.70+ | n8n 1.70+ |

The CLI gives clear error messages when an endpoint isn't available:

GET /data-tables is not available on your n8n instance. This feature may require a newer n8n version.

Configuration

Config is stored at ~/.n8n-cli/config.json with file permissions set to 0600:

{
  "profiles": {
    "default": { "url": "https://n8n.example.com", "apiKey": "..." },
    "staging": { "url": "https://staging.n8n.example.com", "apiKey": "..." }
  },
  "defaultProfile": "default"
}

Config resolution (highest priority wins):

1. CLI flags (--url, --api-key)
2. Environment variables (N8N_URL, N8N_API_KEY)
3. Profile in config file
4. .env file in current directory
5. Default: http://localhost:5678

For AI Agents

This CLI is designed to be used by AI agents (Claude Code, Cursor, Copilot) via the Bash tool:

1. --json on every command for machine-readable output
2. docs command — 921-line structured reference the agent reads once
3. Compound commands reduce round-trips (overview, health-check, search)
4. Structured errors with suggestion field for self-correction
5. Semantic exit codes for branching logic
6. Templates — one-liner to deploy complex workflows

The MCP server is available as a fallback for environments without shell access.

License

MIT

Built by LeadGrow