@lhi/n8m

v1.0.3

Published

3 months ago

Agentic n8n CLI wrapper - A Skill Bridge for n8n workflow automation

Downloads

131

Generate, modify, test, and deploy n8n workflows from the command line using AI.

Stop clicking. Start shipping. n8m is an open-source CLI that wraps your n8n instance with an agentic AI layer. Describe what you want in plain English — the agent designs, builds, validates, and deploys it.

No account. No server. Bring your own AI key and your n8n instance.

Installation

# Option A: Run without installing (npx)
npx @lhi/n8m <command>

# Option B: Install globally
npm install -g @lhi/n8m

Setup

1. Configure your AI provider

n8m stores credentials in ~/.n8m/config.json so they persist across sessions — including npx invocations.

# OpenAI
npx @lhi/n8m config --ai-provider openai --ai-key sk-...

# Anthropic (Claude)
npx @lhi/n8m config --ai-provider anthropic --ai-key sk-ant-...

# Google Gemini
npx @lhi/n8m config --ai-provider gemini --ai-key AIza...

# Any OpenAI-compatible API (Ollama, Groq, Together, LM Studio, etc.)
npx @lhi/n8m config --ai-base-url http://localhost:11434/v1 --ai-key ollama --ai-model llama3

You can also use environment variables or a .env file — stored config takes priority; env vars are used as fallback when no config file value is set:

| Variable | Description | | ------------- | -------------------------------------------------------- | | AI_PROVIDER | Preset: openai, anthropic, or gemini | | AI_API_KEY | API key for your provider | | AI_MODEL | Override the model (optional) | | AI_BASE_URL | Custom base URL for any OpenAI-compatible API (optional) |

Default models per provider: gpt-4o · claude-sonnet-4-6 · gemini-2.5-flash

2. Configure your n8n instance

npx @lhi/n8m config --n8n-url https://your-n8n.example.com --n8n-key <your-n8n-api-key>

Credentials are saved locally to ~/.n8m/config.json. You can also use environment variables N8N_API_URL and N8N_API_KEY instead.

Commands

`n8m create` — Generate a workflow

Describe what you want and the agentic pipeline designs, builds, and validates it.

n8m create "Send a Slack message whenever a new row is added to a Google Sheet"

# Save to a specific file
n8m create "Daily weather summary email" --output ./workflows/weather.json

# Open a multiline editor for complex descriptions
n8m create --multiline

The agent runs through three stages:

Architect — designs the blueprint and identifies required nodes
Engineer — generates the workflow JSON
QA — validates the result; loops back to Engineer if issues are found

The finished workflow is saved as an organized project folder (default: ./workflows/<project-slug>/). Each project folder contains:

workflow.json: The generated n8n workflow.
README.md: Automatic documentation including a Mermaid.js diagram and an AI-generated summary.

`n8m modify` — Modify an existing workflow

Modify a local file or a live workflow on your instance using natural language.

# Modify a local file
n8m modify ./workflows/slack-notifier.json "Add error handling to the HTTP node"

# Browse and select from local files + remote instance
n8m modify

# Multiline instructions
n8m modify --multiline

After modification you'll be prompted to save locally (organized into its project folder), deploy to your instance, or run a test.

`n8m doc` — Generate documentation

Generate visual and text documentation for existing local or remote workflows.

# Document a local workflow file
n8m doc ./workflows/my-workflow.json

# Browse and select from local files + remote instance
n8m doc

Generates a README.md in the workflow's project directory.
Includes a Mermaid.js flowchart of the workflow logic.
Includes an AI-generated summary of the nodes and execution flow.
Automatically organizes loose .json files into project folders.

`n8m test` — Validate and auto-repair a workflow

Validates a workflow against your n8n instance. If it fails, the AI repair loop kicks in — analyzing the error, applying fixes, and retrying automatically.

# Test a local file or remote workflow (browse to select)
n8m test ./workflows/my-flow.json
n8m test

# Generate 3 diverse AI test scenarios (happy path, edge case, error)
n8m test --ai-scenarios

# Use a specific fixture file for offline testing
n8m test --fixture .n8m/fixtures/abc123.json
n8m test -f ./my-fixture.json

Resolves and deploys sub-workflow dependencies automatically
After a passing live test, prompts to save a fixture for future offline runs
When a fixture exists for a workflow, prompts to run offline (no n8n calls)
After a passing test, prompts to deploy or save the validated/repaired version
Auto-documents: Generates or updates the project README.md upon saving.
All temporary assets are deleted on exit

Offline testing with fixtures

n8m can capture real execution data from n8n and replay it offline — no live instance, credentials, or external API calls needed.

First run — capture a fixture:

n8m test                          # runs live against your n8n instance
# → Save fixture for future offline runs? [Y/n]  ← answer Y
# → .n8m/fixtures/<workflowId>.json created

Subsequent runs — replay offline:

n8m test
# → Fixture found from Mar 4, 2026, 10:30 AM. Run offline? [Y/n]

The offline mode uses your real node-by-node execution data, so the AI evaluator works with actual production outputs rather than mocked data. The AI healing loop still runs — if the captured execution shows an error, n8m will try to fix it and evaluate the fix against the real fixture data.

`n8m fixture` — Manage test fixtures

Two ways to create a fixture:

# Pull real execution data from n8n (no test run required)
n8m fixture capture <workflowId>

# Browse local files + remote instance interactively
n8m fixture capture

# Scaffold an empty template to fill in by hand
n8m fixture init <workflowId>

capture connects to your n8n instance, fetches the most recent executions for the workflow, and presents an interactive menu to pick which one to save. You'll be prompted for a fixture name (e.g. happy-path, missing-field) and expected outcome (pass or fail). Fixtures are saved to .n8m/fixtures/<workflowId>/<name>.json.

n8m fixture capture abc123
# → Fetching executions for workflow abc123...
# → ? Select an execution to capture:
# →   #177916  success  3/4/2026, 10:48:47 AM
# →   #177914  success  3/4/2026, 10:48:23 AM
# → ❯ #177913  error    3/4/2026, 10:47:59 AM
# → Name this fixture (e.g. happy-path, missing-field, bad-auth): error-case
# → Expected test outcome: fail
# → Fixture saved to .n8m/fixtures/abc123/error-case.json
# →   Workflow: My Workflow
# →   Execution: error · 5 node(s) captured

Multiple named fixtures per workflow let you test different scenarios (happy path, edge cases, error handling) with one command:

n8m test --fixture .n8m/fixtures/abc123           # run ALL fixtures for a workflow
n8m test --fixture .n8m/fixtures/abc123/error-case.json  # run one specific fixture

init creates an empty template when you want to define the fixture data yourself, without needing a live execution first.

{
  "$schema": "../../node_modules/n8m/dist/fixture-schema.json",
  "version": "1.0",
  "workflowId": "abc123",
  "workflowName": "My Workflow",
  "description": "happy-path",
  "expectedOutcome": "pass",
  "workflow": { "name": "My Workflow", "nodes": [], "connections": {} },
  "execution": {
    "status": "success",
    "data": {
      "resultData": {
        "error": null,
        "runData": {
          "Your Node Name": [{ "json": { "key": "value" } }]
        }
      }
    }
  }
}

Fill in execution.data.resultData.runData with the actual output of each node (keyed by exact node name). Then test against it:

n8m test --fixture .n8m/fixtures/abc123/happy-path.json

Fixture files are project-local (.n8m/fixtures/) and should be committed to your repo so your team can run the same offline tests. Add the $schema field to get autocomplete and validation in any editor that supports JSON Schema.

`n8m deploy` — Push a workflow to n8n

Deploy a local workflow JSON directly to your n8n instance.

n8m deploy ./workflows/my-flow.json

# Activate the workflow immediately after deployment
n8m deploy ./workflows/my-flow.json --activate

# Non-interactive: always update the existing workflow (useful in CI)
n8m deploy ./workflows/my-flow.json --update

# Non-interactive: always create a new workflow, ignoring any existing ID
n8m deploy ./workflows/my-flow.json --force-create

`n8m learn` — Build the pattern library

Extract reusable engineering knowledge from validated workflows and store it so the AI engineer applies the same proven techniques in future generations.

# Interactive: pick a workflow from ./workflows/
n8m learn

# Learn from a specific workflow
n8m learn ./workflows/my-flow/workflow.json

# Batch-generate patterns for every workflow in the directory
n8m learn --all

# Import patterns from a GitHub archive (awesome-n8n style)
n8m learn --github owner/repo
n8m learn --github owner/repo@main --github-path patterns/google
n8m learn --github owner/repo --token ghp_xxx   # or set GITHUB_TOKEN env var

How it works:

Local mode: The AI reads a validated workflow JSON, identifies the techniques it demonstrates, extracts critical rules (including gotchas to avoid), and writes a .md pattern file to .n8m/patterns/.
GitHub mode: Fetches .md pattern files from any public GitHub repo via the GitHub API. Shows a checkbox menu so you choose exactly which patterns to import. Recurses into subdirectories automatically.

Patterns are Markdown files with a  comment. When you run n8m create, the engineer searches all pattern files and injects any that match the workflow's goal into the prompt — teaching it to reproduce proven approaches exactly.

.n8m/patterns/          ← your project-local library (user patterns)
docs/patterns/          ← built-in patterns shipped with n8m

User patterns in .n8m/patterns/ take priority over built-in patterns. A pattern file with the same filename overrides the built-in version, so you can customize any default.

Contributing default patterns (for n8m maintainers):

# Generate docs/patterns/ from every workflow in ./workflows/
npm run generate-patterns

# Overwrite any already-existing pattern files
npm run generate-patterns -- --overwrite

# Preview what would be written without touching the filesystem
npm run generate-patterns -- --dry-run

The script scans workflows/ recursively, calls the AI on each workflow.json, and writes the result to docs/patterns/<slug>.md. Patterns in docs/patterns/ are included in the npm package and available to all users automatically.

Pattern file format:

<!-- keywords: bigquery, google bigquery, sql, merge, http request -->

# Pattern: BigQuery Operations via HTTP Request

## Critical Rules
- NEVER use n8n-nodes-base.googleBigQuery — it returns no output for DDL/DML.
  Always use n8n-nodes-base.httpRequest with the BigQuery REST API.

## DDL / DML Queries
...

`n8m mcp` — Launch the MCP server

Expose n8m's agentic capabilities as tools to any Model Context Protocol client (Claude Desktop, Cursor, etc.).

n8m mcp
# → Starting n8m MCP Server...

The server runs over stdio and registers the following tools:

| Tool | Description | |---|---| | create_workflow | Generate an n8n workflow from a natural-language goal | | modify_workflow | Modify an existing workflow JSON using natural language instructions | | test_workflow | Deploy a workflow ephemerally to n8n and validate it | | deploy_workflow | Create or update a workflow on the configured n8n instance | | get_workflow | Fetch a workflow from n8n by ID | | list_workflows | List all workflows on the n8n instance | | delete_workflow | Delete a workflow from n8n by ID | | generate_docs | Generate a Mermaid diagram and README for a workflow JSON |

Add it to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "n8m": {
      "command": "npx",
      "args": ["@lhi/n8m", "mcp"]
    }
  }
}

`n8m resume` — Resume a paused session

The agent can pause mid-run for human review (HITL). Resume it with its thread ID.

n8m resume <thread-id>

Sessions are persisted to a local SQLite database, so they survive crashes and restarts.

`n8m prune` — Clean up your instance

Removes duplicate workflows and leftover test artifacts ([n8m:test:*] prefixed names).

# Preview what would be deleted
n8m prune --dry-run

# Delete without confirmation
n8m prune --force

`n8m config` — Manage configuration

All credentials are saved to ~/.n8m/config.json and persist across sessions (including npx invocations).

# Set AI provider
n8m config --ai-provider openai --ai-key sk-...
n8m config --ai-provider anthropic --ai-key sk-ant-...
n8m config --ai-provider gemini --ai-key AIza...

# Override model or set a custom OpenAI-compatible endpoint
n8m config --ai-model gpt-4o-mini
n8m config --ai-base-url http://localhost:11434/v1 --ai-key ollama --ai-model llama3

# Set n8n instance
n8m config --n8n-url https://your-n8n.example.com --n8n-key <key>

# Show current config
n8m config

Architecture

Developer → n8m create "..."
               │
               ▼
        ┌─────────────┐      .n8m/patterns/    docs/patterns/
        │  Architect  │  ◄── RAG: node defs + matched patterns
        └──────┬──────┘
               │
               ▼
        ┌─────────────┐
        │  Engineer   │◄──────────────┐
        └──────┬──────┘               │ repair loop
               │                      │
               ▼                      │
        ┌─────────────┐       ┌───────┴─────┐
        │     QA      │──────►│  (failed)   │
        └──────┬──────┘       └─────────────┘
               │ passed
               ▼
        ./workflows/<slug>/
           ├── workflow.json
           └── README.md (with Mermaid diagram)


Developer → n8m learn <workflow.json>
               │
               ▼
          AI analyzes validated workflow
               │
               ▼
        .n8m/patterns/<slug>.md  ← feeds back into Engineer on next create

Local first: credentials and workflow files live on your machine
Organized Projects: Workflows are grouped into folders with auto-generated documentation
SQLite persistence: session state survives interruptions
HITL pauses: the agent stops for your review before committing
Bring your own AI: works with OpenAI, Claude, Gemini, Ollama, or any OpenAI-compatible API
Self-improving: every validated workflow you learn from strengthens future generations

For developers: See the Developer Guide for a deep-dive into the agentic graph internals, RAG implementation, how to add new agent nodes, and how to extend the CLI.

Local Development

git clone https://github.com/Lee-Holdings-International/n8m.git
cd n8m
npm install

# Watch mode
npm run dev

# Run directly
./bin/run.js help

Roadmap

Shipped

[x] Agentic graph (Architect → Engineer → Supervisor → Reviewer → QA)
[x] SQLite session persistence
[x] HITL interrupts and resume
[x] Sub-workflow dependency resolution in tests
[x] Open source — no account required
[x] Multi-provider AI support (OpenAI, Claude, Gemini, Ollama, any OpenAI-compatible API)
[x] Automatic documentation generation (Mermaid + AI Summary)
[x] Project-based folder organization
[x] AI-driven test scenario generation (--ai-scenarios)
[x] Static node type reference & fallback mechanism
[x] Multi-workflow project generation support
[x] Fixture record & replay — offline testing with real execution data
[x] Hand-crafted fixture scaffolding (n8m fixture init) with JSON Schema
[x] Pattern library — extract & reuse knowledge from validated workflows (n8m learn)
[x] GitHub pattern archive import (n8m learn --github owner/repo)
[x] MCP server — expose n8m as tools for Claude Desktop and other MCP clients
[x] n8m rollback — restore a workflow to a previous git-tracked version with a single command
[x] Credential awareness — AI consults available credential types on the target instance so it stops generating nodes it can't authenticate
[x] MCP server expanded to 8 tools — full workflow lifecycle from any MCP client: create, modify, test, deploy, get, list, delete, generate docs
[x] Non-interactive deploy flags — --update and --force-create for CI/scripted use without interactive prompts

Near-term

[ ] n8m watch — file-system watcher that auto-deploys on save with live reload in the n8n editor
[ ] n8m diff — human-readable structural diff between two workflow versions (nodes added/removed/changed)
[ ] Parallel test runs — fire multiple fixture payloads concurrently and report aggregate pass/fail

Medium-term

[ ] n8m debug — attach to a running execution and stream node-by-node output to the terminal in real time
[ ] n8m chat — interactive REPL where every message applies an incremental AI edit and immediately re-tests
[ ] Workflow linter — static analysis before deploy: dead branches, missing error handlers, unconnected nodes, credential gaps
[ ] n8m learn --from-executions — scrape recent successful executions and distil reusable patterns into .n8m/patterns/ automatically
[ ] Multi-instance deploy — deploy the same workflow to staging and production in one command with environment-variable substitution

Longer-term

[ ] Visual diff — n8m diff --ui opens a side-by-side workflow comparison in the n8n canvas
[ ] Workflow marketplace — n8m publish / n8m install <slug> to share and consume community patterns with version pinning
[ ] Execution replay — record a live execution and automatically promote it to a fixture, closing the capture loop entirely
[ ] Agent memory across sessions — the engineer remembers which node patterns worked well for a given integration and prefers them on future builds
[ ] LangGraph trace export — export the full agentic reasoning trace (Architect → Engineer → Reviewer → QA) as a structured log for debugging and auditing

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Installation

Setup

1. Configure your AI provider

2. Configure your n8n instance

Commands

n8m create — Generate a workflow

n8m modify — Modify an existing workflow

n8m doc — Generate documentation

n8m test — Validate and auto-repair a workflow

Offline testing with fixtures

n8m fixture — Manage test fixtures

n8m deploy — Push a workflow to n8n

n8m learn — Build the pattern library

n8m mcp — Launch the MCP server

n8m resume — Resume a paused session

n8m prune — Clean up your instance

n8m config — Manage configuration