WF CMS Purge

A CLI tool to hard-delete all records in designated Webflow CMS collections for a specified site.

Configuration

Typically Webflow CMS Purge is used in the context of a project, alongside development and testing scripts. As such, the configuration is local.

Edit your .gitignore file, if your project is source-controlled, and add .wf-cms-purge to ensure your configuration and API keys are not checked in.

Create a .wf-cms-purge file in your project directory with the following format:

[my-site-1]
WEBFLOW_API_KEY=your_api_key_here

[my-site-2]
WEBFLOW_API_KEY=another_api_key_here

Each section is identified by the site slug (shortName), and must contain a WEBFLOW_API_KEY for accessing that site's data.

Getting Your API Key

1. Go to your Webflow site settings
2. Navigate to the Integrations tab
3. Generate a new API token with appropriate permissions
4. Copy the token to your .wf-cms-purge config file

Usage

wf-cms-purge <site-slug> <collection-slug>

Example

wf-cms-purge my-site-1 dealerships

Options

• -c, --config <path> - Specify a custom path to the config file (default: ./.wf-cms-purge)
• --noprompt - Automatically confirm all prompts
• --quiet - Suppress non-error output (shows only errors and a final completion message with site/collection)
• -V, --version - Output the version number
• -h, --help - Display help information

How It Works

The purge process follows these steps:

1. Validation

• Verifies the site exists by matching the provided slug
• Confirms the collection exists within that site
• Retrieves the site ID and collection ID for subsequent operations

2. Work Report

• Counts the total number of items in the collection
• Displays the count and requests user confirmation before proceeding
• Exits if the user declines or if there are no items to delete

3. Unlink All Other Collections

• Scans all collections in the site for Reference or Multi-Reference fields pointing to the target collection
• Identifies required reference fields and prompts the user to make them optional
• Iterates through every record in collections with references and nulls the fields pointing to the collection being purged
• Also checks the purge collection itself for self-references
• Re-publishes already-published items to ensure the field is fully cleared
• Uses batch operations where possible to minimize API rate-limit issues

4. Purge Collection

• Bulk unpublishes live items (up to 100 per request)
• Bulk deletes staged items (up to 100 per request)

Features

• Rate Limiting: Automatically handles Webflow API rate limits with exponential backoff
• Error Handling: Comprehensive error handling with detailed error messages
• Logging: Clear console output showing progress at each step
• Safety Checks: Multiple confirmation prompts before destructive operations
• Reference Management: Automatically handles collection references to prevent deletion errors

API Rate Limits

This tool is designed to respect Webflow's API rate limits:

• Implements a rate limiter to prevent exceeding API quotas
• Automatically retries failed requests with exponential backoff
• Processes requests sequentially to avoid overwhelming the API
• Waits at least 100ms between consecutive API calls

Warnings

• This operation is destructive and cannot be undone
• Always test on a development site first
• Ensure you have backups of your data before running
• The tool will request confirmation before deleting data
• Required reference fields will be made optional (with user confirmation)

Troubleshooting

"Configuration file not found"

Make sure you've created a .wf-cms-purge file in the current working directory with the correct format, or pass -c to point to it.

"No configuration found for site"

Verify that your site slug matches exactly with the section name in your .wf-cms-purge file.

"Webflow API Error"

• Check that your API key is valid and has the necessary permissions
• Ensure your API token hasn't expired
• Verify you have sufficient API rate limit quota

Rate Limit Errors

The tool automatically handles rate limits, but if you consistently hit limits:

• The tool will wait and retry automatically
• Check your Webflow plan's API limits
• Consider running during off-peak hours