Workflow Management

n8n-deploy stores workflow configuration in a local database. Push and pull by name or ID (copy from the n8n UI URL) - the database tracks paths and server links.

🆕 Adding New Workflows

n8n-deploy supports adding workflows that don’t have a server-assigned ID yet. This is common when:

• Creating new workflows from scratch
• Exporting workflows from the n8n UI (which may not include the server ID)

How It Works

1. Add workflow without ID - Tool generates a temporary draft_{uuid} ID
2. Push to server - Server assigns a permanent ID
3. Automatic update - Draft ID replaced with server ID, file renamed

# Add workflow without ID (generates draft_xxx temporary ID)
n8n-deploy wf add my-workflow.json --link-remote production
# Output: WARNING: No ID found. Generated draft ID: draft_abc123...

# Push to server (replaces draft ID with server-assigned ID)
n8n-deploy wf push draft_abc123 --remote production
# Output: Updating draft ID to server ID xYz789...
# Filename preserved: my-workflow.json (not renamed)

The draft ID is temporary. After your first push, the database entry is updated with the permanent server-assigned ID. Your custom filename is preserved.

🌟 Workflow Operations

List Workflows

Local Workflows

n8n-deploy wf list

Remote Server Workflows

n8n-deploy wf list-server --remote http://n8n.example.com:5678

Pull Workflow from Remote Server

# Pull specific workflow
n8n-deploy wf pull "Customer Onboarding" --remote http://n8n.example.com:5678

# Pull multiple workflows at once (NEW in v0.9.0)
n8n-deploy wf pull wf1 wf2 wf3 --remote http://n8n.example.com:5678

# Pull with custom filename (for new workflows, single workflow only)
n8n-deploy wf pull "Customer Onboarding" --remote production --filename customer-onboarding.json

# Pull with custom flow directory
n8n-deploy wf pull "Customer Onboarding" --remote production --flow-dir /path/to/workflows

# Non-interactive mode (uses default filenames, no prompts)
n8n-deploy wf pull wf1 wf2 --remote production --non-interactive

When pulling a new workflow, you’ll be prompted to enter a filename. Use --filename to specify it directly. Note: --filename only works with single workflow; for multiple workflows, default filenames are used.

Push Workflow to Remote Server

# Push by workflow name
n8n-deploy wf push "Deployment Pipeline" --remote production

# Push by workflow ID
n8n-deploy wf push deAVBp391wvomsWY --remote production

# Push by filename
n8n-deploy wf push my-workflow.json --remote production

# Push multiple workflows at once (NEW in v0.9.0)
n8n-deploy wf push wf1 wf2 wf3 --remote production

Multi-workflow output example:

[1/3] Processing: wf1
Pushed workflow 'wf1' to server

[2/3] Processing: wf2
Pushed workflow 'wf2' to server

[3/3] Processing: wf3
Pushed workflow 'wf3' to server

=== Push Summary ===
  OK   wf1
  OK   wf2
  OK   wf3

All 3 workflow(s) pushed successfully

Workflow Resolution: The push command accepts workflow ID, name, or filename. Resolution priority: ID → Name → Filename.

Workflow files should be managed with version control (git). Use db backup for database metadata, API keys, and server configurations.

Delete Workflow

Remove a workflow from the n8n server and/or local database. Breaking change in v0.9.0: At least one flag is now required.

# Remove from database only (untrack)
n8n-deploy wf delete "Customer Onboarding" --db

# Delete from server only (keep in database)
n8n-deploy wf delete "Customer Onboarding" --server

# Delete from both server and database
n8n-deploy wf delete "Customer Onboarding" --db --server

# Skip confirmation prompt
n8n-deploy wf delete "Customer Onboarding" --db --server --yes

# Override server
n8n-deploy wf delete workflow-name --server --remote staging

# Self-signed certificates
n8n-deploy wf delete workflow-name --server --skip-ssl-verify

Breaking Change (v0.9.0): The wf delete command now requires at least one of --db or --server flags. This prevents accidental deletions and gives you explicit control over what gets removed.

The local JSON file is NEVER deleted. You manage workflow files via version control (git).

Draft workflows: Workflows with draft IDs (draft_*) are only removed from the database since they don’t exist on any server yet.

🔗 Link Command - Update Workflow Metadata

The wf link command updates stored workflow metadata without performing push/pull operations. This is useful for:

• Changing the stored flow directory
• Associating a workflow with a different server

Update Flow Directory

# Update stored flow-dir for a workflow
n8n-deploy wf link my-workflow --flow-dir ./new-location

# Future push/pull will automatically use this path
n8n-deploy wf push my-workflow  # Uses ./new-location

Link to Different Server

# Associate workflow with a server
n8n-deploy wf link my-workflow --server production

# Future push uses this server automatically
n8n-deploy wf push my-workflow  # No --remote needed

Combine options: Update multiple settings at once: n8n-deploy wf link my-workflow --flow-dir ./workflows --server staging

---

🔄 Path and Server Resolution

When you add a workflow with --flow-dir and --link-remote, those values are stored. Future commands use them automatically:

# Add with configuration
n8n-deploy wf add workflow.json --flow-dir ./workflows --link-remote production

# Push/pull - just the name
n8n-deploy wf push my-workflow
n8n-deploy wf pull my-workflow

# Override when needed
n8n-deploy wf push my-workflow --remote staging

Resolution Order

Setting	Priority
Flow directory	CLI flag > Database > Environment > Current dir
Server	CLI flag > Database > Environment

Explicit flags always take precedence.

---

🔍 Smart Workflow Lookup

All workflow commands support flexible name matching (new in v0.9.0):

# All of these resolve to the same workflow "My Workflow"
n8n-deploy wf push "My Workflow"      # Exact name
n8n-deploy wf push "my workflow"      # Case-insensitive
n8n-deploy wf push my-workflow        # Slug-style (hyphens)
n8n-deploy wf push my_workflow        # Slug-style (underscores)
n8n-deploy wf push my-workflow.json   # Filename lookup

Lookup Priority:

1. Workflow ID - Exact match (e.g., deAVBp391wvomsWY)
2. Workflow name - Exact match (e.g., My Workflow)
3. Case-insensitive - Ignores case (e.g., my workflow)
4. Slug-style - Converts spaces/dashes/underscores (e.g., my-workflow)
5. Filename - Auto-appends .json if missing (e.g., my-workflow.json)

This makes commands more forgiving. You can type n8n-deploy wf push customer-onboarding instead of remembering the exact capitalization “Customer Onboarding”.

---

🔍 Advanced Workflow Management

Search Workflows

# Search workflows by name or tag
n8n-deploy wf search "customer"

Workflow Statistics

# Show workflow statistics
n8n-deploy wf stats

Tip: Always use quotes for workflow names with spaces. Example: n8n-deploy wf pull "Customer Onboarding"

Leverage the --no-emoji flag for scripting to get clean, parseable output.

🧩 Workflow File Management

Custom Filenames

Workflows can use any filename you choose:

# Add workflow with custom filename (preserved)
n8n-deploy wf add my-descriptive-name.json

# Push using the filename
n8n-deploy wf push my-descriptive-name.json --remote production

Filenames are preserved - my-workflow.json stays my-workflow.json, not renamed to {id}.json.

Workflow Status Tracking

• Workflows tracked in SQLite database
• Metadata includes:
  • Workflow name
  • Custom filename (file column)
  • File folder location
  • Timestamps
  • Server linkage

Verbose Logging

Use verbose flags to debug workflow operations:

# Basic verbose - shows HTTP requests
n8n-deploy -v wf push workflow-name --remote production

# Extended verbose - shows request/response details
n8n-deploy -vv wf push workflow-name --remote production

# Flag can be placed at root or subcommand level
n8n-deploy wf -v push workflow-name    # Same as above
n8n-deploy wf -vv pull workflow-name   # Works at subcommand level

Troubleshooting

• Verify server URL and API key
• Check file permissions
• Ensure workflow names are exact
• Use --skip-ssl-verify for self-signed certificates
• Use -v or -vv flags to see HTTP request details

Push operations: Read-only fields are automatically stripped before sending to n8n server. See Troubleshooting for details.

📖 Related Guides

• Folder Synchronization - Sync entire folders of workflows
• Configuration
• API Key Management
• Troubleshooting

💻 Example Workflow Management Scenario

# Create server and add API key
n8n-deploy server create my_server http://n8n.example.com:5678
echo "your-api-key" | n8n-deploy apikey add - --name my_key --server my_server

# List remote workflows
n8n-deploy wf list-server --remote my_server

# Pull a specific workflow
n8n-deploy wf pull "Customer Onboarding" --remote my_server

# Search workflows
n8n-deploy wf search "customer"