n8n-workflow-sync

Sync workflows and credentials between your local repository and your n8n instance.

Features

• Pull workflows from your n8n instance to local JSON files
• Push workflows from local files to your n8n instance
• Create credentials interactively with schema validation
• Automatically create/update workflows (upsert)
• Push credentials with workflows from LastPass
• Skip archived workflows

Prerequisites

• Node.js (v18 or higher recommended)
• A running n8n instance
• n8n API key (see setup instructions below)
• LastPass CLI (if using credentials sync)

Installation

Install the package globally via npm:

npm install -g @_lenga/n8n-workflows-sync

Or with yarn:

yarn global add @_lenga/n8n-workflows-sync

Configuration

1. Get your n8n API Key

1. Open your n8n instance
2. Go to Settings → API
3. Create a new API key
4. Copy the key

2. Set up environment variables

Create a .env file in the root directory (or copy from .env-sample):

cp .env-sample .env

Edit the .env file with your settings:

# N8N local run data and cache
N8N_USER_FOLDER=./

# Instance parameters
N8N_INSTANCE_URL=http://localhost:5678
N8N_API_KEY=your-api-key-here
LOCAL_WORKFLOWS_PATH=./src/workflows

# LastPass folder for storing credentials
LPASS_FOLDER=n8n

Environment Variables:

• N8N_INSTANCE_URL: URL of your n8n instance
• N8N_API_KEY: Your n8n API key
• LOCAL_WORKFLOWS_PATH: Local directory for workflow JSON files
• LPASS_FOLDER: LastPass folder where credentials will be stored (default: n8n)

3. Set up credentials (optional)

If you want to sync credentials with LastPass, ensure you have LastPass CLI installed and logged in:

lpass login [email protected]

The tool will automatically detect credentials used in your workflows and sync them from LastPass.

Quick Reference

# View all commands
n8nsync --help

# Pull workflows
n8nsync pull

# Push workflows
n8nsync push

# Push single credential from LastPass
n8nsync push-credential <name>

# Create credential (push to LastPass)
n8nsync create-credential <type> <name>

# Create credential (print to console)
n8nsync create-credential <type> <name> -p

# Inspect credential schema
n8nsync inspect-schema <type>

# Version
n8nsync --version

Usage

Pull workflows from n8n to local files

n8nsync pull

This will:

• Connect to your n8n instance
• Download all non-archived workflows
• Save them as JSON files in LOCAL_WORKFLOWS_PATH

Push workflows (and credentials) to n8n

n8nsync push

This will:

1. Read all workflow JSON files from LOCAL_WORKFLOWS_PATH
2. Extract credentials referenced in workflow nodes
3. Push credentials from LastPass to n8n (if LastPass CLI is configured)
4. Create or update workflows in your n8n instance with updated credential IDs

Push a single credential from LastPass

n8nsync push-credential <credentialName>

This will:

1. Fetch the credential from LastPass using the credential name
2. Extract the credential type from the LastPass Notes JSON
3. Push it to your n8n instance

Examples:

# Push a Slack API credential
n8nsync push-credential "My Slack Cred"

# Push a GitHub token
n8nsync push-credential "GitHub Token"

# Push an OpenAI API key
n8nsync push-credential "OpenAI Key"

Note: The credential type is automatically extracted from the type field in the LastPass Notes JSON.

LastPass entry format:

The LastPass entry must have the credential data stored as JSON in the Notes field. The structure is:

<Entry Name> [id: <id>]
URL: <url>
Notes: {
  "name": "credential-name",
  "type": "credentialType",
  "data": {
    // credential-specific fields
  }
}

Example for GitHub API:

n8n - Jose Nunez/[email protected] [id: 123456]
URL: http://sn
Notes: {
  "name": "[email protected]",
  "type": "githubApi",
  "data": {
    "user": "username",
    "accessToken": "ghp_xxxxxxxxxxxxx"
  }
}

Example for OpenAI API:

n8n - OpenAI Key [id: 789012]
URL: http://sn
Notes: {
  "name": "OpenAI Key",
  "type": "openAiApi",
  "data": {
    "apiKey": "sk-xxxxxxxxxxxxx"
  }
}

The tool will extract the JSON from the Notes field and send it directly to n8n without modification.

Create credentials interactively

n8nsync create-credential <credentialType> <credentialName> [-p]

This will:

1. Fetch the credential schema from your n8n instance
2. Interactively prompt you for required fields (with defaults)
3. Prompt you for optional fields (press Enter to skip)
4. By default: Push the credential to LastPass as a secure note
5. With -p flag: Print the credential JSON to console only

Examples:

# Create and push to LastPass (default)
n8nsync create-credential slackApi "My Slack Credential"

# Create and print to console only
n8nsync create-credential slackApi "My Slack Credential" -p

# Create an OpenAI API credential and push to LastPass
n8nsync create-credential openAiApi "OpenAI Key"

# Create a Google Drive OAuth2 credential and print to console
n8nsync create-credential googleDriveOAuth2Api "My Google Drive" -p

Modes:

1. Default (Push to LastPass): The credential is saved to LastPass as a secure note in the folder specified by LPASS_FOLDER env variable
2. Print Mode (-p flag): The credential JSON is printed to console for manual copying

Finding credential types:

To find the correct credential type name:

1. Look at your existing workflows - credential types are listed in the node definitions
2. Check the n8n documentation
3. Common types include: slackApi, openAiApi, githubApi, googleDriveOAuth2Api, etc.

Tips:

• Press Enter on optional fields to skip them (they won't be included in the JSON)
• Press Enter on required fields to use default values
• For complex fields (arrays, objects), provide valid JSON

Get help

n8nsync --help
n8nsync <command> --help

Workflow Structure

Workflows are stored as JSON files in the format:

{
  "name": "My Workflow",
  "nodes": [...],
  "connections": {...},
  "settings": {...},
  "staticData": {...}
}

Credentials

The credentials sync feature automatically extracts credentials from your workflow files and retrieves them from LastPass CLI.

How it works:

1. The tool scans all workflow JSON files for credential references
2. Extracts unique credentials (by name and type)
3. Retrieves credential data from LastPass using the credential name
4. Pushes credentials to n8n
5. Updates workflow nodes with the new credential IDs

LastPass entry format:

Each LastPass entry name must match the credential name in your workflows. The credential data must be stored as JSON in the Notes field with the following structure:

{
  "name": "credential-name",
  "type": "credentialType",
  "data": {
    // credential-specific fields
  }
}

Examples:

GitHub API:

{
  "name": "[email protected]",
  "type": "githubApi",
  "data": {
    "user": "username",
    "accessToken": "ghp_xxxxxxxxxxxxx"
  }
}

OpenAI API:

{
  "name": "OpenAI Key",
  "type": "openAiApi",
  "data": {
    "apiKey": "sk-xxxxxxxxxxxxx"
  }
}

Slack OAuth2:

{
  "name": "Slack OAuth",
  "type": "slackOAuth2Api",
  "data": {
    "clientId": "client-id",
    "clientSecret": "client-secret",
    "sendAdditionalBodyProperties": false,
    "additionalBodyProperties": []
  }
}

Common Use Cases

Backup workflows to version control

# Pull workflows from n8n
n8nsync pull

# Commit to git
git add src/workflows/
git commit -m "Backup workflows"
git push

Deploy workflows to another instance

# Update .env to point to new instance
N8N_INSTANCE_URL=https://production.n8n.example.com
N8N_API_KEY=production-api-key

# Push workflows
n8nsync push

Sync workflows between environments

# Pull from dev
N8N_INSTANCE_URL=http://localhost:5678 n8nsync pull

# Push to staging
N8N_INSTANCE_URL=https://staging.n8n.example.com n8nsync push

Troubleshooting

"env var N8N_INSTANCE_URL not found"

Make sure your .env file exists and contains the required variables.

"Failed to fetch workflows"

• Check that your n8n instance is running
• Verify your API key is correct and has proper permissions
• Ensure the instance URL is accessible

Credentials not syncing

• Verify LastPass CLI is installed: lpass --version
• Ensure you're logged in: lpass status
• Check that credential names in your workflows match LastPass entry names exactly
• Verify that the credential type is supported (see Credentials section)

Development

Setting up for development

If you want to contribute or modify the package:

# Clone the repository
git clone <repository-url>
cd n8n-workflow-sync

# Install dependencies
yarn install

# Build the project
yarn build

Development commands

# Run n8nsync in dev mode
yarn dev:n8nsync <command> [options]

# Or use individual dev commands:
yarn dev:pull                                    # Pull workflows (dev mode)
yarn dev:push                                    # Push workflows (dev mode)
yarn dev:push-credential <name>                  # Push single credential (dev mode)
yarn dev:create-credential <type> <name>         # Create credential (dev mode)
yarn dev:inspect-schema <type>                   # Inspect schema (dev mode)

# Build TypeScript to JavaScript
yarn build

# Run local n8n instance for testing
yarn dev

# Lint code
yarn lint

# Format code
yarn format

# Check formatting
yarn format:check

Project structure

n8n-workflow-sync/
├── src/
│   ├── index.ts                   # Main CLI entry point (n8nsync)
│   ├── pull.ts                    # Pull workflows from n8n
│   ├── push.ts                    # Push workflows and credentials to n8n
│   ├── pushCredentials.ts         # Push credentials from LastPass
│   ├── pushSingleCredential.ts    # Push single credential from LastPass
│   ├── createCredential.ts        # Interactive credential creator
│   ├── credentialSchemaHelper.ts  # Schema-based credential utilities
│   ├── inspectCredentialSchema.ts # Inspect credential schemas
│   ├── settings.ts                # Load environment variables
│   ├── constants.ts               # Constants and configuration
│   ├── error.ts                   # Error handling utilities
│   └── workflows/                 # Local workflow storage (JSON files)
├── dist/                          # Compiled JavaScript (generated)
├── .env                           # Environment variables (not in repo)
├── .env-sample                    # Example environment variables
├── CREDENTIAL_SCHEMAS.md          # Schema-based credential documentation
└── package.json                   # Package configuration

Publishing

# Build and publish to npm
yarn prepublishOnly
npm publish

License

ISC

Author

Jose Nunez