n8n-sync

Synchronize N8N workflows between environments with automatic credential and sub-workflow remapping.

A rich, interactive CLI tool that solves the critical pain point of moving N8N workflows across environments (dev → staging → production). When you copy a workflow between N8N instances, credential IDs and sub-workflow IDs break because they're unique per environment. n8n-sync handles the remapping automatically through an intuitive terminal UI inspired by modern CLI tools like Claude Code.

Features

• Multi-Environment Management — Configure unlimited N8N environments (URL + API key) with automatic API validation
• Smart Workflow Sync — Copy or update workflows between environments with intelligent status detection (New / Updated / Up-to-Date)
• Credential & Sub-Workflow Matching — Interactive UI to map credentials and sub-workflow references that differ by ID across environments, with auto-match by name and persistent match storage
• Git-Style Diff View — Compare source and destination workflows line-by-line with color-coded diffs and optional filtering of credential/sub-workflow nodes
• Workflow Remapping — Custom source↔destination workflow matching when names differ between environments
• Batch Sync — Select and synchronize multiple workflows in one session with dependency-aware commit ordering (sub-workflows are committed before parent workflows)
• Backup & Restore — Every commit backs up the destination workflow; restore previous versions with a single keypress
• Workflow List Filtering — Real-time search to quickly find workflows in large environments
• Dependencies Tree View — Visualize sub-workflow dependencies as a tree structure with cascade selection — select a parent to automatically select all its sub-workflows for batch sync
• Brief/Full View Toggle — Switch between compact view (full workflow names, no dates) and detailed view (truncated names with date columns)
• Action History — Full log of all user actions (syncs, remaps, credential matches, environment changes)
• In-Memory Staging — All changes are staged in memory until you explicitly commit — nothing touches the destination until you say so

Quick Start

Prerequisites

• Node.js ≥ 18
• At least two N8N instances with API access enabled

Install

npm install --global n8n-sync

Run

n8n-sync

Or run without installing:

npx n8n-sync

First Run

On first launch, n8n-sync guides you through setting up your environments:

1. Add environments — Provide a name, N8N instance URL, and API key for each environment
2. Validation — Each environment is validated via API ping to ensure correct configuration
3. Start syncing — Select source and destination environments, then browse and sync workflows

How to get your N8N API key: In your N8N instance, go to Settings → API → Create API Key. The key needs read/write access to workflows and read access to credentials.

Usage

Core Workflow

Setup Environments → Select Source & Destination → Browse Workflows → Select & Sync → Review & Commit

1. Select environments — Pick source (where workflows come from) and destination (where they go)
2. Browse workflows — See all source workflows with sync status color-coding
3. Select workflows — Use Space to select one or more workflows for sync
4. Match credentials & sub-workflows — For each node that uses credentials or calls sub-workflows, map them to the destination equivalents
5. Review & commit — Review staged changes, then commit to push everything to the destination

Keyboard Controls

n8n-sync is fully keyboard-driven. Here are the key controls by screen:

Workflows List

| Key | Action | |-----|--------| | ↑ ↓ | Navigate workflows | | Space | Select/deselect workflow for sync | | Enter | Start sync for selected workflows | | D | View diff (Updated workflows only) | | M | Remap workflow (custom source↔destination matching) | | F | Filter workflows by name | | R | Refresh workflow list from both environments | | A | Toggle all (select/deselect all workflows) | | T | View dependency tree | | V | Toggle Brief/Full View | | B | Restore from backup (when backup exists) | | S | Open environment settings | | L | View action history | | Q | Back to environment selection |

Sync Process (Per-Workflow Matching)

| Key | Action | |-----|--------| | ← → | Navigate between nodes | | ↑ ↓ | Browse available matches | | Enter | Confirm selected match | | S | Skip current node (revisit later) | | F | Finish — save matches and proceed | | Q | Quit current workflow (with confirmation) |

Batch Sync Overview

| Key | Action | |-----|--------| | ← → | Navigate between workflows | | Enter | Enter workflow for matching | | C | Commit all finished workflows | | Q | Back to workflows list (with confirmation) |

Diff View

| Key | Action | |-----|--------| | ↑ ↓ | Scroll through diff | | N | Jump to next change | | P | Jump to previous change | | H | Toggle Hide Creds/Sub nodes | | Q | Back to workflows list |

Environment Settings

| Key | Action | |-----|--------| | ↑ ↓ | Navigate environments | | A | Add new environment | | E | Edit selected environment | | D | Delete selected environment | | Q | Back |

Dependencies View

| Key | Action | |-----|--------| | ↑ ↓ | Navigate tree nodes | | Space | Select/deselect (cascades to all sub-workflows) | | Q | Back to workflows list |

Filter Mode (Workflows List)

| Key | Action | |-----|--------| | Type | Real-time search filtering | | Enter | Apply filter and return to list | | Esc | Cancel and reset filter |

How It Works

Credential & Sub-Workflow Matching

The core problem n8n-sync solves: when you copy a workflow from Environment A to Environment B, every node that references a credential or sub-workflow breaks because IDs are unique per environment.

n8n-sync detects these nodes and provides an interactive matching UI:

1. Auto-match by name — If a credential/sub-workflow has the same name on both environments, it's matched automatically
2. Auto-match from history — Previously confirmed matches (stored in SQLite) are applied automatically
3. Auto-match batch workflows — In batch mode, sub-workflow nodes can match with other workflows in the same batch
4. Manual matching — For unmatched nodes, browse available options and select the correct match
5. Skip & revisit — Skip nodes you're unsure about and come back later

If all nodes auto-match, you get a prompt to apply all and skip to the next workflow.

Batch Sub-Workflow Sync

When syncing multiple workflows where one calls another as a sub-workflow, n8n-sync handles the dependency chain:

• Batch workflows appear in the sub-workflow match list (marked with ⚡ and colored magenta)
• Dependencies are automatically sorted — sub-workflows are committed before parent workflows
• Source IDs are resolved to actual destination IDs at commit time

Backup & Restore

Every time you commit an updated workflow, n8n-sync saves the original destination workflow as a backup:

• One backup per workflow per destination environment (newer backups replace older ones)
• Press B on the workflows list to restore from backup
• Backups are stored locally in SQLite — no external dependencies
• After successful restore, the backup is removed

Dependencies Tree

When syncing workflows that use sub-workflows (Execute Workflow nodes), it's important to sync them together. The Dependencies View (T from the Workflows List) shows all source workflows in a tree structure:

• Root nodes are workflows not called as sub-workflows by any other workflow
• Child nodes are sub-workflows, nested under their parent with tree connectors (├─ / └─)
• Cascade selection — selecting a parent automatically selects all its descendants, making it easy to select an entire dependency chain for batch sync
• Selections sync bidirectionally with the main Workflows List — selections made in the tree persist when switching back

In-Memory Staging

Nothing is pushed to the destination environment until you explicitly commit:

• All credential/sub-workflow matches are staged in memory
• You can review, re-enter, and modify any workflow before committing
• Commit requires explicit confirmation
• Only fully-processed workflows are included in the commit

Architecture

┌─────────────────────────────────────────────┐
│  CLI Entry (meow)                           │
│  └─ render(<App />)                         │
├─────────────────────────────────────────────┤
│  React 19 + Ink 6 (Terminal UI)             │
│  └─ MemoryRouter (react-router)             │
│     ├─ /          Welcome/Splash            │
│     ├─ /setup     Initial Setup             │
│     ├─ /select    Environment Selection     │
│     ├─ /workflows Workflows List            │
│     ├─ /diff      Workflow Differences      │
│     ├─ /remap     Workflow Remapping        │
│     ├─ /sync      Sync Process              │
│     ├─ /settings  Environment Settings      │
│     └─ /history   Actions History           │
├─────────────────────────────────────────────┤
│  Domain Services                            │
│  ├─ Environments (CRUD, validation)         │
│  ├─ Workflows (fetch, compare, diff, remap) │
│  ├─ Sync (credential/sub-wf matching)       │
│  └─ History (action logging)                │
├─────────────────────────────────────────────┤
│  Data Layer                                 │
│  ├─ N8N REST API (source of truth)          │
│  └─ SQLite (persistent local storage)       │
└─────────────────────────────────────────────┘

Domain-Driven Structure

Components, hooks, and services are organized by feature domain:

src/
├── domains/
│   ├── environments/    # Environment CRUD, API validation, form/list UI
│   ├── workflows/       # Workflow list, diff view, remapping, restore
│   ├── sync/            # Sync process, credential/sub-workflow matching, batch sync
│   └── history/         # Action history logging and display
├── shared/              # Shared components (progress bar, environment context)
├── routes/              # Route page components (compose domains into screens)
├── db/                  # SQLite setup, schema, typed repositories
│   └── repositories/    # Per-table data access (environments, mappings, backups, etc.)
├── app.tsx              # Root component with MemoryRouter + routes
└── cli.tsx              # CLI entry point (meow arg parsing → render App)

Key Patterns

• Hooks + Components separation — Hooks (use-*.ts) manage state and logic; components (*.tsx) handle rendering and input
• Service layer — Services sit between UI hooks and DB repositories, adding validation, API calls, and action logging
• Repository pattern — Typed synchronous data access matching better-sqlite3's sync API
• View state machines — Route pages manage sub-views (list/add/edit/delete/confirm) via React state, not extra routes
• Shared context — Selected environment pair is available to all routes via React Context

Tech Stack

Core

| Technology | Version | Purpose | |-----------|---------|---------| | React | 19.x | UI component framework | | Ink | 6.x | React renderer for terminal UIs | | TypeScript | 5.x | Type-safe development | | react-router | 7.x | MemoryRouter for screen navigation | | better-sqlite3 | latest | Synchronous SQLite driver | | meow | 14.x | CLI argument parsing | | diff | 8.x | Text differencing for workflow comparison |

UI Components

| Package | Purpose | |---------|---------| | ink-text-input | Text input fields | | ink-select-input | Navigable select lists | | ink-scroll-view | Scrollable content areas | | ink-spinner | Loading indicators | | ink-big-text | ASCII art logo on splash screen |

Data Persistence

SQLite database stored at ~/.n8n-sync/data.db with the following tables:

| Table | Purpose | |-------|---------| | environments | N8N instance configs (name, URL, API key) | | workflow_mappings | Custom source↔destination workflow ID mappings | | credential_matches | Stored credential ID mappings per workflow/node | | subworkflow_matches | Stored sub-workflow ID mappings per workflow/node | | workflow_backups | Pre-commit destination workflow backups for undo | | action_history | Log of all user actions with timestamps | | sync_records | Track which workflows were synced and when |

Development

Setup

git clone https://github.com/CollectiveXP/n8n-sync.git
cd n8n-sync
npm install

Scripts

| Command | Description | |---------|-------------| | npm run dev | Watch mode — recompiles TypeScript on change | | npm run build | One-time TypeScript compilation | | npm run type-check | Type checking only (tsc --noEmit) | | npm run lint | ESLint check | | npm run lint:fix | ESLint auto-fix | | npm run format | Prettier auto-format |

Code Quality

• ESLint — Flat config with TypeScript, React, React Hooks, and import plugins
• Prettier — No semicolons, single quotes, trailing commas (es5)
• Husky + lint-staged — Pre-commit hooks run Prettier → ESLint → TypeScript check on staged files
• Zero tolerance — Zero TypeScript errors and zero ESLint warnings required

Running Locally

# Build and run
npm run build
node dist/cli.js

# Or use watch mode during development
npm run dev
# In another terminal:
node dist/cli.js

License

MIT