wrangler deployments

The wrangler deployments commands allow you to view deployment history for Workers using Gradual Rollouts. A deployment represents a specific traffic split configuration across one or more Worker Versions.

Subcommands

wrangler deployments list - Display the 10 most recent deployments
wrangler deployments status - View the current production state
wrangler deployments view - Deprecated, redirects to other commands

Deployments are created when you run wrangler versions deploy or wrangler rollback. Each deployment tracks which versions are receiving traffic and at what percentages.

list

Display the 10 most recent deployments of your Worker, showing the history of how traffic has been distributed across versions over time.

wrangler deployments list [OPTIONS]

Options

--name

string

Name of the Worker. Can also be specified in your configuration file.

--json

boolean

default:"false"

Display output as clean JSON format instead of formatted text.

Example

# List deployments for the current Worker
wrangler deployments list

# List deployments for a specific Worker
wrangler deployments list --name my-worker

# Get JSON output
wrangler deployments list --json

Output

For each deployment, displays:

Created - When the deployment was created (ISO timestamp)
Author - Email of the user who created the deployment
Source - How the deployment was created:
- Wrangler 🤠 - Created via Wrangler CLI
- Dashboard 🖥️ - Created via Cloudflare Dashboard
- API 📡 - Created via Cloudflare API
- Terraform 🏗️ - Created via Terraform
- Rollback - Created via wrangler rollback
- Upload, Secret Change, Promotion - Triggered by specific actions
Message - Optional deployment message (if provided)
Version(s) - List of versions in the deployment with their traffic percentages

For each version within a deployment:

Traffic percentage
Version ID
Created timestamp
Tag annotation
Message annotation

Example Output

Created:     2024-03-03T14:30:00.000Z
Author:      [email protected]
Source:      Wrangler 🤠
Message:     Gradual rollout of new API
Version(s):  (90%) 10000000-0000-0000-0000-000000000000
                 Created:  2024-03-03T10:00:00.000Z
                     Tag:  v2.1.0
                 Message:  New API endpoints

             (10%) 20000000-0000-0000-0000-000000000000
                 Created:  2024-03-03T14:00:00.000Z
                     Tag:  v2.2.0
                 Message:  Performance improvements

Created:     2024-03-02T09:15:00.000Z
Author:      [email protected]
Source:      Wrangler 🤠
Message:     Initial deployment
Version(s):  (100%) 10000000-0000-0000-0000-000000000000
                 Created:  2024-03-03T10:00:00.000Z
                     Tag:  v2.1.0
                 Message:  New API endpoints

status

View the current state of your production deployment, showing which versions are currently receiving traffic.

wrangler deployments status [OPTIONS]

Options

--name

string

Name of the Worker. Can also be specified in your configuration file.

--json

boolean

default:"false"

Display output as clean JSON format instead of formatted text.

Example

# View current deployment status
wrangler deployments status

# View status for a specific Worker
wrangler deployments status --name my-worker

# Get JSON output
wrangler deployments status --json

Output

Displays the current (most recent) deployment with:

Created - When this deployment was created
Author - Who created this deployment
Source - How this deployment was created
Message - Optional deployment message
Version(s) - Current versions and their traffic distribution

For each active version:

Traffic percentage
Version ID
Created timestamp
Tag and message annotations

Example Output

Created:     2024-03-03T14:30:00.000Z
Author:      [email protected]
Source:      Wrangler 🤠
Message:     Production release
Version(s):  (100%) 10000000-0000-0000-0000-000000000000
                 Created:  2024-03-03T10:00:00.000Z
                     Tag:  v2.1.0
                 Message:  New API endpoints

Use Cases

Check current traffic split

Before deploying a new version, use status to see your current deployment state:

wrangler deployments status

This helps you understand the baseline before making changes.

Verify deployment success

After running wrangler versions deploy, confirm the deployment:

wrangler versions deploy new-version@50 old-version@50
wrangler deployments status

Monitor rollout progress

During a gradual rollout, check status between percentage increases:

# Deploy at 10%
wrangler versions deploy new@10 old@90
# Check metrics, then increase
wrangler deployments status
wrangler versions deploy new@50 old@50

view

The deployments view command has been deprecated and renamed.

# Old command (deprecated)
wrangler deployments view

# New command
wrangler deployments status

# Old command (deprecated)
wrangler deployments view <deployment-id>

# New command
wrangler versions view <version-id>

If you try to use wrangler deployments view, you’ll receive an error message directing you to the correct command.

Understanding Deployments

Deployment vs. Version

Version: A snapshot of your Worker code, configuration, and bindings. Created with wrangler versions upload.
Deployment: A traffic routing configuration that specifies which versions receive what percentage of requests. Created with wrangler versions deploy.

A single deployment can route traffic to multiple versions simultaneously, enabling gradual rollouts and A/B testing.

Deployment Sources

Deployments can be created through multiple sources:

Source	Description	Triggered By
Wrangler	CLI deployments	`wrangler versions deploy`
Dashboard	Web UI deployments	Cloudflare Dashboard
API	Direct API calls	Cloudflare API
Terraform	Infrastructure as code	Terraform provider
Rollback	Rollback operations	`wrangler rollback`
Upload	Automatic deployment	Some upload operations
Secret Change	Secret modifications	Secret updates that trigger deployment

Deployment Lifecycle

Upload versions

Create one or more versions using wrangler versions upload.

Create deployment

Deploy versions with traffic distribution using wrangler versions deploy.

Monitor

Track metrics for each version to ensure stability.

Adjust traffic

Gradually shift traffic percentages with new deployments.

Complete rollout

Deploy the new version to 100% of traffic once validated.

JSON Output Format

When using --json, the output follows this structure:

[
  {
    "id": "deployment-id",
    "source": "wrangler",
    "created_on": "2024-03-03T14:30:00.000Z",
    "author_email": "[email protected]",
    "annotations": {
      "workers/message": "Deployment message",
      "workers/triggered_by": "upload"
    },
    "versions": [
      {
        "version_id": "10000000-0000-0000-0000-000000000000",
        "percentage": 100
      }
    ]
  }
]

This format is useful for:

Automation and scripting
Integration with monitoring tools
Programmatic deployment verification
Building custom dashboards

wrangler versions deploy - Create a new deployment
wrangler versions list - List available versions
wrangler rollback - Rollback to a previous version
wrangler versions view - View version details

Common Workflows

Viewing Deployment History

# See recent deployment history
wrangler deployments list

# Check what's currently deployed
wrangler deployments status

# Review specific version details
wrangler versions view <version-id>

Debugging Deployment Issues

Check current state

wrangler deployments status

Review deployment history

wrangler deployments list

Examine version details

wrangler versions view <version-id>

Rollback if needed

wrangler rollback <version-id>

Monitoring a Gradual Rollout

# 1. Deploy new version at 10%
wrangler versions deploy new@10 old@90

# 2. Check status
wrangler deployments status

# 3. Monitor metrics externally
# ... check error rates, latency, etc.

# 4. Increase to 50% if stable
wrangler versions deploy new@50 old@50
wrangler deployments status

# 5. Complete rollout
wrangler versions deploy new@100
wrangler deployments status

Best Practices

Use deployment messages

Always add meaningful messages to your deployments:

wrangler versions deploy new@100 --message "Fix for authentication bug"

This helps track changes when reviewing deployments list.

Check status before and after changes

Verify the current state before deploying:

# Before
wrangler deployments status
# Deploy
wrangler versions deploy new@50 old@50
# After
wrangler deployments status

Use JSON output for automation

Parse JSON output in scripts for programmatic deployment verification:

STATUS=$(wrangler deployments status --json)
# Parse and validate the deployment state

Keep deployment history for auditing

The deployment list provides an audit trail. Use it to:

Track who deployed what and when
Understand deployment patterns
Debug issues by correlating deployments with incidents

Essential Commands

Version Management

Storage Commands

Service Commands

Pages Commands

Configuration

Subcommands

list

Options

Example

Output

Example Output

status

Options

Example

Output

Example Output

Use Cases

view

Understanding Deployments

Deployment vs. Version

Deployment Sources

Deployment Lifecycle

JSON Output Format

Common Workflows

Viewing Deployment History

Debugging Deployment Issues

Monitoring a Gradual Rollout

Best Practices

Build docs developers (and LLMs) love

Essential Commands

Version Management

Storage Commands

Service Commands

Pages Commands

Configuration

​Subcommands

​list

​Options

​Example

​Output

​Example Output

​status

​Options

​Example

​Output

​Example Output

​Use Cases

​view

​Understanding Deployments

​Deployment vs. Version

​Deployment Sources

​Deployment Lifecycle

​JSON Output Format

​Related Commands

​Common Workflows

​Viewing Deployment History

​Debugging Deployment Issues

​Monitoring a Gradual Rollout

​Best Practices

Build docs developers (and LLMs) love

Subcommands

list

Options

Example

Output

Example Output

status

Options

Example

Output

Example Output

Use Cases

view

Understanding Deployments

Deployment vs. Version

Deployment Sources

Deployment Lifecycle

JSON Output Format

Related Commands

Common Workflows

Viewing Deployment History

Debugging Deployment Issues

Monitoring a Gradual Rollout

Best Practices