@integratingfactor/n8n-workflow-cli

n8n Workflow CLI

A powerful CLI tool for managing n8n workflows across multiple environments with support for tags, validation, and automated deployment.

Why Use This Tool?

• 📁 Workflows as Code - Store workflows in Git alongside your project code

• 🏷️ Organized by Categories - Tag and filter workflows by project/team using n8n tags

• 🔄 Bi-directional Sync - Pull workflows from n8n, edit locally, and deploy back

• ✅ Workflow validation - Comprehensive JSON schema validation

• 🔄 Pull/Push workflows - Sync workflows between environments

• 🛡️ Safe Deployments - New workflows are created inactive; no duplicate workflows

• ⚡ Parallel deployment - Deploy multiple workflows simultaneously

• 🔍 Dry-run mode - Test deployments without making changes

Installation

Install globally to use across all your workflow projects:

npm install -g @integratingfactor/n8n-workflow-cli

Verify installation:

n8n-workflow-cli -h

CLI Commands

pull

Pull workflows from n8n to local files:

n8n-workflow-cli pull [options]

Options:

• --category <category> - Only pull workflows with this category tag

Examples:

# Pull all workflows
n8n-workflow-cli pull

# Pull only business workflows
n8n-workflow-cli pull --category business

diff

Compare local workflows with remote n8n instance:

n8n-workflow-cli diff [workflow]

Arguments:

• workflow (optional) - Specific workflow file, category, or omit to compare all

Examples:

# Compare all workflows
n8n-workflow-cli diff

# Compare specific workflow
n8n-workflow-cli diff workflows/business/my-workflow.json

# Compare all workflows in a category
n8n-workflow-cli diff business

Output:

• Modified: Workflows that differ between local and remote
• Local Only: Workflows present locally but not in n8n
• Remote Only: Workflows present in n8n but not locally
• Identical: Workflows that match between local and remote

deploy

Deploy local workflows to n8n:

n8n-workflow-cli deploy [options]

Options:

• --dry-run - Show what would be deployed without making changes

Examples:

# Deploy all workflows
n8n-workflow-cli deploy


# Preview deployment without making changes
n8n-workflow-cli deploy --dry-run

Behavior:

• New workflows: Created as inactive (must be manually activated in n8n)
• Existing workflows: Updated with local changes
• Duplicate prevention: Checks for existing workflows by name before creating
• Tags: Automatically creates and assigns category tags

list

List workflows:

n8n-workflow-cli list [options]

Options:

• --remote - List workflows from n8n instance (also) along with local files

Examples:

# List local workflows
n8n-workflow-cli list

# List remote workflows
n8n-workflow-cli list --remote

validate

Validate local workflow JSON files:

n8n-workflow-cli validate

Checks for:

• Valid JSON structure
• Required workflow fields
• Proper node configuration
• Connection validity

Project Structure

A typical workflow project looks like this:

my-n8n-workflows/
├── .env                   # Environment variables (gitignored)
├── .gitignore             # Ignore .env and other files
├── n8n.config.json        # Tool configuration
├── README.md              # Project documentation
└── workflows/             # Workflow JSON files
    ├── business/
    │   ├── customer-onboarding.json
    │   └── invoice-processing.json
    ├── management/
    │   └── team-reports.json
    └── shared/
        └── send-notification.json

Quick Start

Workflow repo setup

Create a new directory for your n8n workflows:

mkdir my-n8n-workflows
cd my-n8n-workflows
git init

Create n8n.config.json in your project root:

{
  "workflowsDir": "./workflows",
  "categories": ["business", "management", "shared"]
}

Configuration Options:

• workflowsDir: Directory where workflow JSON files are stored (relative to config file)
• categories: List of workflow categories (used as n8n tags for organization)

💡 Important: The n8n.config.json file should be committed to your repository.

Configure n8n Connection

The CLI uses two simple environment variables:

• N8N_API_URL - Your n8n instance API URL (must end with /api/v1)
• N8N_API_KEY - Your n8n API key (from Settings → API in n8n)

Option 1: Using .env file (recommended for local development)

# Edit .env with your values
N8N_API_URL=https://n8n.dev.company.com/api/v1
N8N_API_KEY=your-dev-api-key

# Add `.env` to your `.gitignore`:
echo ".env" >> .gitignore

Option 2: Using shell exports

export N8N_API_URL="https://n8n.dev.company.com/api/v1"
export N8N_API_KEY="your-dev-api-key"

Categories Configuration

Categories help organize workflows into folders in your repository:

• Define categories in the categories array - customize for your project needs (e.g., ["business", "management", "shared"])

• Commit the config - The n8n.config.json file with your categories should be committed so the team shares the same organization

• Tag workflows in n8n - Only workflows with tags matching a category name will be pulled

Pull workflows from your n8n instance

This creates workflow JSON files in your workflowsDir, organized by category.

# Pull all workflows with matching category tags
n8n-workflow-cli pull

# Pull only workflows tagged with "business"
n8n-workflow-cli pull --category business

Validate workflows

n8n-workflow-cli validate

Make Changes and Deploy

Edit workflow files locally, then deploy:

# deploy a specific workflow
n8n-workflow-cli deploy workflows/business/my-workflow.json

# deploy all workflows
n8n-workflow-cli deploy

Important: New workflows are created as inactive for safety. You must:

• Verify the workflow in n8n UI

• Configure credentials and connections

• Test the workflow

• Manually activate it when ready

Best Practices

1. Version Control

• Commit workflow JSON files to Git
• Use meaningful commit messages describing workflow changes
• Review diffs before committing to catch unintended changes
• Keep .env in .gitignore (never commit credentials)

2. Team Collaboration

• Use pull requests for workflow changes
• Document complex workflows in comments
• Use consistent category naming across team
• Set up CI/CD to validate workflows automatically

3. Multi-Environment Management

• Keep separate n8n instances for dev/staging/prod
• Test workflows in dev before deploying to prod
• Use environment-specific credentials in n8n
• Document environment differences in your project README

4. Workflow Organization

• Use meaningful workflow names
• Group related workflows in categories
• Keep workflows focused on single responsibilities
• Document dependencies between workflows

5. Deployment Safety

• Always run validate before deploying
• Use --dry-run to preview changes
• Test new workflows in n8n before activating
• Review credential mappings after deployment

Troubleshooting

"URL must end with /api/v1"

Make sure your N8N_API_URL includes the full API path:

# ✅ Correct
N8N_API_URL=https://n8n.example.com/api/v1

# ❌ Wrong
N8N_API_URL=https://n8n.example.com

"Authentication failed"

• Verify your API key is correct
• Check that API access is enabled in n8n (Settings → API)
• Ensure your n8n instance is accessible from your machine

"Workflow not found (404)"

If a workflow was deleted in n8n but exists locally:

• The tool will check if a workflow with the same name exists
• If found, it updates the existing workflow
• If not found, it creates a new workflow (inactive)
• Local file is updated with the correct workflow ID

Duplicate Workflows

The tool prevents duplicates by checking workflow names before creating. If you see duplicates:

• They were likely created outside this tool
• Manually delete duplicates in n8n UI
• Run pull to sync local files with n8n state

Support & Contributing

• Issues: Report bugs and request features on GitHub Issues
• Development: See DEVELOPMENT.md for contributing guidelines
• License: MIT

What's New

See CHANGELOG.md for version history and release notes.

Made with ❤️ for the n8n community