n8n-workflow-search-replace

A command-line tool that performs bulk find-and-replace operations across all workflows in an n8n instance. Useful for updating API endpoints, URLs, config values, or any other string that appears in workflow JSON.

Features

• Arbitrary Search & Replace: Find and replace any string across all workflows
• Multiple Replacements: Many-to-one or paired find/replace in a single run
• Dry Run Mode: Preview changes before applying (default)
• Connection Test: Verify API connectivity with --test
• Rich Console Output: Beautiful progress tracking and reporting
• Safe Operations: Confirmation prompts and error handling

Quick Start

1. Clone and install:

git clone <repo-url>
cd n8n-workflow-search-replace
pip install -r requirements.txt

2. Configure .env:

cp .env.example .env
# Edit .env with your n8n details

3. Run:

# Test connectivity
python n8n_search_replace.py --test

# Preview changes (dry run)
python n8n_search_replace.py --find "api.old-domain.com" --replace "api.new-domain.com"

# Apply changes
python n8n_search_replace.py --find "api.old-domain.com" --replace "api.new-domain.com" --live

Configuration

Environment Variables

Create a .env file with the following variables:

# N8N API Configuration
N8N_API_KEY=your_n8n_api_key_here
N8N_BASE_URL=your_n8n_instance_url_here

Getting Your N8N API Key

1. Log into your n8n instance
2. Go to Settings -> Personal -> API Keys
3. Click Create API Key
4. Copy the generated key to your .env file

Note: n8n uses a custom header format X-N8N-API-KEY (not standard Bearer tokens).

Usage

Test connectivity

python n8n_search_replace.py --test

Verifies API connectivity and reports the number of workflows on the instance.

Single replacement

python n8n_search_replace.py --find "api.old-domain.com" --replace "api.new-domain.com"

Many-to-one (multiple finds, one replacement)

python n8n_search_replace.py \
  --find "staging.example.com" \
  --find "dev.example.com" \
  --replace "prod.example.com"

Paired replacements (each find gets its own replace)

python n8n_search_replace.py \
  --find "api.old-domain.com" --replace "api.new-domain.com" \
  --find "v1/endpoint" --replace "v2/endpoint" \
  --live

Sample Output (dry run)

Starting bulk search & replace:
   staging.example.com -> prod.example.com
Target instance: https://n8n.example.com
Running in DRY RUN mode - no changes will be made
Successfully connected to N8N API
Instance: https://n8n.example.com
Workflows: 86

Found 86 workflows

                 Workflows to Update
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Name         ┃ ID           ┃ Active ┃ Matches Found       ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ My Workflow  │ abc123...    │ Yes    │ staging.example.com │
└──────────────┴──────────────┴────────┴─────────────────────┘

Found 1 workflows to update
DRY RUN COMPLETE - Use --live to apply changes

How It Works

1. Connects to your n8n instance using the API key
2. Fetches all workflows from the instance
3. Scans each workflow's JSON for the search strings
4. Replaces found strings with their replacements
5. Updates workflows back via the n8n API

The tool performs find-and-replace on the serialized workflow JSON, ensuring all occurrences are updated.

Troubleshooting

401 Unauthorized Error

• Cause: Invalid or missing n8n API key
• Solution:
  1. Verify your API key is correct in .env
  2. Ensure the API key hasn't expired
  3. Check that you have proper permissions in n8n

Connection Issues

• Cause: Network connectivity or URL misconfiguration
• Solution:
  1. Run python n8n_search_replace.py --test to diagnose
  2. Verify your n8n instance URL in a browser
  3. Check if your n8n instance is accessible from your network

No Workflows Found

• Cause: No workflows contain the search strings
• Solution: Verify your --find values match exactly what appears in the workflow JSON

Security Notes

• API Keys: Never commit your .env file to version control
• Private Directory: The private/ folder is gitignored for additional secrets

File Structure

n8n-workflow-search-replace/
├── n8n_search_replace.py   # Main script
├── pyproject.toml          # Project metadata & packaging
├── requirements.txt        # Python dependencies
├── .env.example            # Environment template
├── .env                    # Your secrets (gitignored)
├── .gitignore              # Git ignore rules
└── README.md               # This file

Credits

Based on N8N-LLM-Workflow-Bulk-Updater by Daniel Rosehill.