n8n-deploy 0.7.0

n8n-deploy - a simple N8N Workflow Manager with SQLite metadata store

n8n-deploy: Database-First n8n Workflow Management CLI

Overview

n8n-deploy is a Python CLI that remembers your workflow configuration. Built on SQLite, it stores paths, servers, and settings - so deployment commands stay simple.

n8n-deploy wf push my-workflow

The database knows where your workflow lives and which server it belongs to.

Key Features

• 🧠 Smart Configuration

  • Stores workflow paths, server links, and SSL settings
  • Push/pull with just the workflow name
  • Override anytime with explicit flags

• 🚀 Multi-Server Support

  • Push and pull workflows to any n8n server
  • Per-server SSL verification settings
  • API key management with server linking

• 📁 Folder Synchronization (NEW in v0.2.0)

  • Bidirectional folder sync between local and n8n server
  • folder CLI command group for folder operations
  • Automatic folder mapping and tracking

• 📜 Script Synchronization (NEW)

  • Sync external scripts (.js, .cjs, .py) referenced by Execute Command nodes
  • Git-based change detection (only sync modified scripts)
  • Extensible transport plugin system (SCP included)
  • Automatic remote folder creation per workflow

• 💻 Versatile CLI Interface

  • Emoji-rich output for interactive use
  • Script-friendly mode with --no-emoji flag
  • Verbose logging with -v and -vv flags at any command level
  • Comprehensive workflow operations

Installation

# Pip install
pip install n8n-deploy

# Use uv for faster setup and virtual environment
uv venv --python /usr/bin/python3 .venv
source .venv/bin/activate
uv pip install n8n-deploy

Quick Start

# Initialize database
n8n-deploy db init --data-dir ~/.n8n-deploy

# Create server and add API key
n8n-deploy server create production https://n8n.example.com
echo "your-n8n-api-key" | n8n-deploy apikey add - --name "prod-key"

# Configure SSL for self-signed certificates (optional)
n8n-deploy server ssl production --skip-verify

# Link workflow to server with flow directory (automatic server resolution)
n8n-deploy wf add workflow.json --flow-dir ./workflows --link-remote production

# Push/pull uses linked server AND stored flow-dir automatically!
n8n-deploy wf push workflow-name  # No --flow-dir or --remote needed!
n8n-deploy wf pull workflow-name  # Uses stored paths automatically

# Update workflow metadata without push/pull
n8n-deploy wf link my-workflow --flow-dir ./new-location
n8n-deploy wf link my-workflow --server staging
n8n-deploy wf link my-workflow --scripts-path /opt/n8n/scripts/custom

# Override with --remote for ad-hoc operations
n8n-deploy wf push workflow-name --remote staging

# Delete workflow from local database
n8n-deploy wf delete workflow-name

# List workflows from server
n8n-deploy wf server --remote production

# Folder synchronization (NEW in v0.2.0)
n8n-deploy folder sync --remote production  # Sync folders with server

# Script synchronization (sync .js, .cjs, .py files with workflow push)
# Scripts upload to: <base-path>/<workflow-name>/ (e.g., /opt/n8n/scripts/My_Workflow/)
n8n-deploy wf push workflow-name \
  --scripts ./scripts \
  --scripts-host n8n.example.com \
  --scripts-user deploy \
  --scripts-key ~/.ssh/id_rsa \
  --scripts-base-path /opt/n8n/scripts  # Optional, this is the default

# Dry run to see what scripts would sync
n8n-deploy wf push workflow-name --scripts ./scripts --dry-run

# Enable verbose logging for debugging
n8n-deploy -v wf push workflow-name   # Basic verbose
n8n-deploy -vv wf push workflow-name  # Extended verbose

Community & Support

💬 Get Help & Connect:

• Discussions - Ask questions, share ideas, showcase workflows
• Issues - Report bugs or request features
• Documentation - Complete guides and API reference

Discussion Categories:

• 📣 Announcements - Project updates and releases
• 🙏 Q&A - Get help from the community
• 💡 Ideas - Suggest new features
• 🎯 Show and Tell - Share your workflows
• #️⃣ General - Everything else

Configuration

n8n-deploy supports multiple configuration methods:

1. CLI Flags
2. Environment Variables
3. .env Files (in development mode)

Environment Variables

• N8N_DEPLOY_FLOWS_DIR: Workflow files directory
• N8N_DEPLOY_DATA_DIR: Application data directory
• N8N_SERVER_URL: n8n server URL for remote operations
• N8N_SCRIPTS_HOST: Remote host for script sync
• N8N_SCRIPTS_USER: Remote username for script sync
• N8N_SCRIPTS_PORT: SSH port for script sync (default: 22)
• N8N_SCRIPTS_KEY: SSH key file path for script sync
• N8N_SCRIPTS_BASE_PATH: Remote base path for scripts (default: /opt/n8n/scripts)

Documentation

📚 Read the full documentation

Quick Links:

• Getting Started
• Configuration Guide
• Workflow Management
• API Key Management
• Troubleshooting

Contributing

We welcome contributions! Please see our Contributing Guide and Code of Conduct.

Quick Links:

• Developer Guide
• Architecture Overview
• Testing Framework

License

This project is licensed under the MIT License - see the LICENSE file for details.

Requirements

• Python 3.9+
• n8n server (local or remote)
• Basic understanding of workflow management

Performance Note

Designed for efficient workflow management with minimal overhead. Ideal for DevOps, automation engineers, and workflow enthusiasts.