n8n-cli

n8n CLI — n8n Workflow Management for AI Agents

Wrapper around n8n-as-code (n8nac CLI v2.2.1). Manage n8n workflows programmatically from the terminal.

Quick Start

# 1. Start n8n if not running:
docker run -d --name n8n --restart unless-stopped -p 5678:5678 \
  -e N8N_SECURE_COOKIE=false \
  -v ~/.n8n:/home/node/.n8n n8nio/n8n:latest

# 2. Create owner account at http://localhost:5678
#    Or via API:
curl -X POST http://localhost:5678/rest/owner/setup \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@local.dev","firstName":"Admin","lastName":"User","password":"Password123!"}'

# 3. Login to get session cookie:
curl -c /tmp/n8n-cookies.txt -X POST http://localhost:5678/rest/login \
  -H "Content-Type: application/json" \
  -d '{"emailOrLdapLoginId":"admin@local.dev","password":"Password123!"}'

# 4. Create API key:
curl -X POST http://localhost:5678/rest/api-keys \
  -H "Content-Type: application/json" -b /tmp/n8n-cookies.txt \
  -d '{"label":"n8n-cli","scopes":["workflow:list","workflow:read","workflow:create","workflow:update"],"expiresAt":null}'

# 5. Configure n8nac workspace:
echo "<rawApiKey>" | npx n8nac env add local \
  --base-url http://localhost:5678 \
  --sync-folder ~/n8n-workspace/workflows --api-key-stdin

# 6. Use the plugin:
sc n8n-cli self version        # Verify version
sc n8n-cli workflow list       # List all workflows
sc n8n-cli workflow pull <id>  # Download workflow

Commands

Instance & Config

• sc n8n-cli self version — Print n8nac version
• sc n8n-cli self setup — Configure n8n workspace (interactive — runs n8nac setup)
• sc n8n-cli self mcp — Register MCP server in ~/.supercli/mcp.json

Workflow Management

• sc n8n-cli workflow list — List all workflows with status (tracked, remote-only, conflicts)
• sc n8n-cli workflow pull <id> — Download workflow from n8n to local (uses bash wrapper to capture stderr)
• sc n8n-cli workflow push <path> — Upload local workflow to n8n

Passthrough (advanced, use raw n8nac flags)

• sc n8n-cli find <query> — Search workflows by name or ID
• sc n8n-cli test <id> — Trigger workflow via webhook and report outcome
• sc n8n-cli verify <id> — Validate workflow nodes against local schema
• sc n8n-cli convert <file> — Convert between JSON and TypeScript formats
• sc n8n-cli credentials — Manage credential readiness inventory
• sc n8n-cli execution <id> — Inspect workflow executions for debugging
• sc n8n-cli skills — AI tools: search nodes, docs, validate workflows

Setting Up an n8n Instance

Docker (quickest)

docker run -d --name n8n --restart unless-stopped -p 5678:5678 \
  -e N8N_SECURE_COOKIE=false \
  -v ~/.n8n:/home/node/.n8n n8nio/n8n:latest

First-Time Setup

1. Open http://localhost:5678
2. Create owner account (email + password)
3. Go to Settings → API Keys → Create API key with workflow scopes
4. Or use the API (see Quick Start above)

Reset Owner (if needed)

docker exec n8n n8n user-management:reset
docker restart n8n

Then recreate the owner account.

MCP Integration

Register the MCP server so agents can talk to n8n directly:

sc n8n-cli self mcp

This adds a stdio MCP server to ~/.supercli/mcp.json running npx n8nac mcp. Agents get direct MCP tools for n8n operations without going through the CLI.

Working with Workflows

Creating a Workflow via API

curl -s -X POST http://localhost:5678/rest/workflows \
  -H "Content-Type: application/json" -b /tmp/n8n-cookies.txt \
  -d '{"name":"My Workflow","nodes":[{"id":"1","name":"Manual","type":"n8n-nodes-base.manualTrigger","typeVersion":1,"position":[250,300]}],"connections":{},"active":false}'

Pulling Workflows

sc n8n-cli workflow pull <workflow-id>

After pulling, the workflow appears as TRACKED in workflow list. Files are saved to the sync folder.

Telegram Workflow Example

Create a workflow with Manual Trigger → Telegram node:

curl -X POST http://localhost:5678/rest/workflows \
  -H "Content-Type: application/json" -b /tmp/n8n-cookies.txt \
  -d '{"name":"Telegram Notif","nodes":[{"id":"t1","name":"Manual","type":"n8n-nodes-base.manualTrigger","typeVersion":1,"position":[250,300]},{"id":"t2","name":"Send Telegram","type":"n8n-nodes-base.telegram","typeVersion":1,"position":[550,300],"parameters":{"resource":"message","operation":"sendMessage","chatId":{"value":""},"text":{"value":"=Hello from n8n at {{ $now }}"}},"credentials":{"telegramApi":{"id":null,"name":"Telegram Bot"}}}],"connections":{"Manual":{"main":[[{"node":"Send Telegram","type":"main","index":0}]]}},"active":false}'

Then configure the Telegram bot token in the n8n UI under Credentials.

Caveats & Pitfalls

1. n8nac Output Goes to stderr

All n8nac commands (pull, push, list) output progress to stderr, not stdout. The plugin uses a bash wrapper with 2>&1 for pull/push to capture it. Other commands may show empty data.raw if executed without the wrapper — use workflow list afterward to verify changes.

2. n8nac Has No --json Flag

n8nac does not support machine-readable output. All output is human-readable with ANSI escape codes. The parseJson: false adapter setting preserves raw text.

3. Demo/AI Agent Workflows May Fail to Pull

Some pre-installed demo workflows (like "My first AI Agent in n8n") may return "not found on remote" when pulling. This is an upstream n8n-as-code issue with project-scoped workflows. Create your own workflows for reliable pull testing.

4. Workspace Environment Required

n8nac requires a configured workspace environment. Without it, commands fail with "CLI not configured". Use n8nac env add to set one up. The default env name is local — use --env local for commands that need it.

5. API Key Creation Requires Specific Fields

The n8n API expects label, scopes (array), and expiresAt (null for no expiry) when creating API keys. Valid workflow scopes: workflow:list, workflow:read, workflow:create, workflow:update.

6. n8n Owner Reset

If you forget the password or get locked out, use docker exec n8n n8n user-management:reset && docker restart n8n to reset the owner state.

7. MCP Server Requires Running n8n

The n8n-as-code MCP server (npx n8nac mcp) requires the n8n instance to be reachable. It does not start n8n automatically — start n8n first with Docker.

Environment Detection

The n8nac config is stored globally (in ~/.config/n8n-as-code/). The default environment is marked with * in n8nac env list. Commands that don't specify --env use the default.

Best Practices

1. Use workflow list to discover workflow IDs before pulling
2. Pull workflows before editing locally, push after changes
3. Use verify to check node schemas before pushing to avoid runtime errors
4. Combine with playwright-mcp for browser-based n8n testing
5. Keep n8n and n8nac versions in sync — node schemas are built against the latest stable n8n release