Managing redirects at scale

Use this guide to manage project-level redirects from the CLI. You'll add individual redirects, bulk upload from a file, manage versions, and roll back if needed.

Use this block when you already know what you're doing and want the full command sequence. Use the steps below for context and checks.

# 1. Review existing redirects
vercel redirects list --per-page 50
 
# 2. Add individual redirects
vercel redirects add /old-path /new-path --status 301
vercel redirects add /temp-path /new-path --status 302 --preserve-query-params
 
# 3. Bulk upload from a file
vercel redirects upload redirects.csv
 
# 4. Review the staged version before it goes live
vercel redirects list --staged
 
# 5. Check version history
vercel redirects list-versions
 
# 6. Promote a staged version to live
vercel redirects promote <version-id>
 
# IF a redirect version causes problems:
vercel redirects restore <previous-version-id>
 
# 7. Search and remove specific redirects
vercel redirects list --search "/old-blog"
vercel redirects remove /old-blog/post-1

Start by checking what redirects are currently active:

vercel redirects list --per-page 50

To search for a specific redirect pattern:

vercel redirects list --search "/old-blog"

Add a permanent redirect (301) for a URL that has moved permanently:

vercel redirects add /old-path /new-path --status 301

Add a temporary redirect (302) that preserves query parameters:

vercel redirects add /temp-path /new-path --status 302 --preserve-query-params

For case-sensitive matching:

vercel redirects add /API/v1 /api/v1 --status 301 --case-sensitive

Available status codes are 301 (permanent), 302 (temporary), 307 (temporary, preserves method), and 308 (permanent, preserves method).

For site migrations with many redirects, upload them from a CSV file:

vercel redirects upload redirects.csv

To replace all existing redirects:

vercel redirects upload redirects.csv --overwrite

After uploading or adding redirects, review the staged version before it goes live:

vercel redirects list --staged

This shows the redirects that will take effect when you promote the staged version.

View all redirect versions to understand what changed and when:

vercel redirects list-versions

Each version has an ID, name, timestamp, and status. This history lets you track changes and roll back to any previous version.

When you're satisfied with the staged redirects, promote the version to make it live:

vercel redirects promote <version-id>

To remove a redirect you no longer need:

vercel redirects remove /old-path

Use --yes to skip the confirmation prompt:

vercel redirects remove /old-path --yes

If a redirect version causes problems (for example, a redirect loop or incorrect destination), restore a previous version:

vercel redirects list-versions

Find the version ID of the last known good version, then restore it:

vercel redirects restore <previous-version-id>

This immediately reverts the live redirects to the selected version.

• vercel redirects
• Redirects overview
• Project configuration