Wrangler CLI — Complete Reference

Learning Focus

By the end of this module you will be able to use the Wrangler CLI to create, deploy, manage, and debug Cloudflare Pages projects entirely from your terminal — no dashboard required.

What Is Wrangler?

Wrangler is the official CLI tool for the Cloudflare Developer Platform. It manages:

Cloudflare Pages (projects, deployments, domains)
Cloudflare Workers (scripts, routes, triggers)
KV namespaces, D1 databases, R2 buckets, Queues

For Cloudflare Pages specifically, Wrangler lets you:

Deploy without connecting to GitHub (direct upload)
Manage deployments from CI/CD pipelines
Run a local development server
View real-time logs
Configure environment variables and secrets

Installation

Global Install (Recommended)

Install Wrangler globally via npm
npm install -g wrangler

# Verify installation
wrangler --version
# → 3.x.x

Per-Project Install (For CI/CD)

Add Wrangler as a dev dependency
npm install --save-dev wrangler

# Run via npx
npx wrangler --version

Via Package Managers

Alternative package managers
# pnpm
pnpm add -g wrangler

# yarn
yarn global add wrangler

# bun
bun add -g wrangler

Wrangler Version

As of 2024, Wrangler 3.x is the current major version. Always check wrangler --version and upgrade with npm update -g wrangler if needed.

Authentication

Authenticate via browser
wrangler login

# Opens your browser at:
# https://dash.cloudflare.com/oauth2/auth?...
# After authorizing, your token is saved locally at:
# ~/.config/.wrangler/config/default.toml  (Linux/macOS)
# %APPDATA%\wrangler\config\default.toml   (Windows)

API Token (CI/CD / Non-Interactive)

For automated pipelines (GitHub Actions, scripts), use an API token instead of OAuth:

Authenticate with an API token
# Set environment variable
export CLOUDFLARE_API_TOKEN="your-api-token-here"

# Or set in .env (never commit this!)
echo "CLOUDFLARE_API_TOKEN=your-api-token-here" >> .env

# Wrangler automatically picks up CLOUDFLARE_API_TOKEN
wrangler whoami

Creating an API Token:

Go to dash.cloudflare.com/profile/api-tokens
Click Create Token
Use the "Cloudflare Pages: Edit" template, or create a custom token with:
- Account > Cloudflare Pages > Edit
Copy the token (shown only once)

Account ID

Many commands need your Account ID:

Find your Account ID
# From Wrangler
wrangler whoami

# Output:
# ┌─────────────────────────┬──────────────────────────────────┐
# │ Account Name            │ Account ID                       │
# ├─────────────────────────┼──────────────────────────────────┤
# │ Your Name               │ abc123def456...                  │
# └─────────────────────────┴──────────────────────────────────┘

# Set as environment variable
export CLOUDFLARE_ACCOUNT_ID="abc123def456..."

Project Management Commands

List All Pages Projects

List projects
wrangler pages project list

# Output:
# ┌──────────────┬─────────────────────────────────────┬──────────────────────────┐
# │ Name         │ Domains                             │ Created At               │
# ├──────────────┼─────────────────────────────────────┼──────────────────────────┤
# │ my-docs      │ my-docs.pages.dev, docs.example.com │ 2024-01-15T10:00:00.000Z │
# │ my-blog      │ my-blog.pages.dev                   │ 2024-02-20T08:30:00.000Z │
# └──────────────┴─────────────────────────────────────┴──────────────────────────┘

Create a New Pages Project

Create a Pages project (for direct upload workflow)
wrangler pages project create my-docs

# Options:
# --production-branch  Branch to use as production (default: main)
wrangler pages project create my-docs --production-branch main

Delete a Pages Project

Delete a Pages project
wrangler pages project delete my-docs

# Confirmation prompt will appear
# Use --yes to skip confirmation in scripts:
wrangler pages project delete my-docs --yes

Deployment Commands

Deploy (Direct Upload — No Git Required)

Deploy a local build directory
# Basic deploy
wrangler pages deploy ./build --project-name my-docs

# With explicit environment
wrangler pages deploy ./build \
  --project-name my-docs \
  --branch main \
  --commit-message "Deploy: update docs"

Flags:

Flag	Description	Example
`--project-name`	Pages project name (required)	`--project-name my-docs`
`--branch`	Branch name for this deployment	`--branch main`
`--commit-message`	Commit message label in dashboard	`--commit-message "v2.0"`
`--commit-hash`	Git commit hash	`--commit-hash abc123`
`--no-bundle`	Skip asset bundling	`--no-bundle`

List Deployments

List all deployments for a project
wrangler pages deployment list --project-name my-docs

# Output:
# ┌─────────────────────┬────────────────┬────────────┬────────────────────────────┐
# │ Deployment ID       │ Branch         │ Status     │ Created At                 │
# ├─────────────────────┼────────────────┼────────────┼────────────────────────────┤
# │ abc123...           │ main           │ Active     │ 2024-04-22T05:00:00.000Z   │
# │ def456...           │ main           │ Inactive   │ 2024-04-21T09:00:00.000Z   │
# │ ghi789...           │ feature/nav    │ Inactive   │ 2024-04-20T14:00:00.000Z   │
# └─────────────────────┴────────────────┴────────────┴────────────────────────────┘

View a Specific Deployment

Inspect a deployment
wrangler pages deployment view <deployment-id> --project-name my-docs

# Shows:
# - Deployment URL
# - Build status (success/failure)
# - Branch and commit info
# - File count and size
# - Timestamps

Rollback to a Previous Deployment

Rollback (re-activate a previous deployment)
# List deployments to find the ID to roll back to
wrangler pages deployment list --project-name my-docs

# Then re-deploy that specific deployment by creating a new one from the same files
# (Cloudflare Pages does not have a native CLI rollback command —
# use the dashboard for one-click rollback, or re-deploy the old commit via Git)

# Via Git rollback:
git revert HEAD
git push origin main
# → Triggers a new build from the reverted state

Dashboard Rollback

For instant rollbacks without a new build, use the Cloudflare dashboard: Workers & Pages → your-project → Deployments → (choose any past deployment) → Rollback

Local Development

Start Local Dev Server

Run Cloudflare Pages locally
# In your Docusaurus project root
# (runs both the Pages static assets AND functions locally)
wrangler pages dev ./build

# With hot-reload via Docusaurus dev server:
# Terminal 1: run Docusaurus dev server
npm run start

# Terminal 2: run wrangler against the dev output
wrangler pages dev http://localhost:3000

Dev Server Options

wrangler pages dev flags
wrangler pages dev ./build \
  --port 8788 \           # Local port (default: 8788)
  --ip 0.0.0.0 \          # Bind to all interfaces
  --live-reload \          # Enable live reload
  --compatibility-date 2024-01-01  # Worker compatibility date

Environment Variables & Secrets

Set Environment Variables (Non-sensitive)

Set environment variables via Wrangler
# For production environment
wrangler pages secret put MY_API_URL \
  --project-name my-docs \
  --env production

# You will be prompted to enter the value interactively
# Value: https://api.example.com

# For preview environment
wrangler pages secret put MY_API_URL \
  --project-name my-docs \
  --env preview

List Secrets

List configured secrets
wrangler pages secret list \
  --project-name my-docs \
  --env production

# Output:
# ┌────────────────┬─────────────────────────────────────────────┐
# │ Name           │ Type                                        │
# ├────────────────┼─────────────────────────────────────────────┤
# │ MY_API_KEY     │ secret_text                                 │
# │ ALGOLIA_KEY    │ secret_text                                 │
# └────────────────┴─────────────────────────────────────────────┘

Delete a Secret

Remove a secret
wrangler pages secret delete MY_API_KEY \
  --project-name my-docs \
  --env production

Bulk Upload from `.env` File

There is no native Wrangler command for bulk env-var upload to Pages. Use a script:

Bulk upload secrets from .env file
#!/usr/bin/env bash
# bulk-push-secrets.sh
PROJECT="my-docs"
ENV="production"

while IFS='=' read -r key value; do
  # Skip comments and empty lines
  [[ "$key" =~ ^#.*$ ]] && continue
  [[ -z "$key" ]] && continue

  echo "Setting secret: $key"
  echo "$value" | wrangler pages secret put "$key" \
    --project-name "$PROJECT" \
    --env "$ENV"
done < .env.production

Logs & Debugging

Tail Real-Time Logs

Stream live logs from Pages Functions
wrangler pages deployment tail \
  --project-name my-docs \
  --env production

# Options:
wrangler pages deployment tail \
  --project-name my-docs \
  --format pretty \           # pretty | json
  --status ok \               # Filter: ok | error | canceled
  --ip 1.2.3.4 \             # Filter by client IP
  --header "User-Agent:curl"  # Filter by request header

Sample output:

[2024-04-22 05:00:01] GET /docs/intro 200 OK (12ms)
[2024-04-22 05:00:03] GET /api/search?q=cloudflare 200 OK (45ms)
[2024-04-22 05:00:07] GET /api/broken 500 Error: TypeError: Cannot read property 'x' of undefined

Filter Logs by Status

Show only errors
wrangler pages deployment tail \
  --project-name my-docs \
  --status error

`wrangler.toml` for Pages

While Pages projects don't require wrangler.toml, you can use it to configure Pages Functions and local dev settings:

wrangler.toml — Pages project
name = "my-docs"
pages_build_output_dir = "build"
compatibility_date = "2024-04-01"

# KV Namespace binding (for Pages Functions)
[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-namespace-id"

# D1 Database binding
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "your-d1-database-id"

# R2 Bucket binding
[[r2_buckets]]
binding = "ASSETS"
bucket_name = "my-assets"

# Environment-specific overrides
[env.production]
vars = { ENVIRONMENT = "production" }

[env.preview]
vars = { ENVIRONMENT = "preview" }

Complete Command Reference

Wrangler Pages — All Commands
# Project management
wrangler pages project list
wrangler pages project create <name> [--production-branch <branch>]
wrangler pages project delete <name> [--yes]

# Deployments
wrangler pages deploy <directory> --project-name <name>
wrangler pages deployment list --project-name <name>
wrangler pages deployment view <id> --project-name <name>

# Local development
wrangler pages dev <directory|url> [--port <port>] [--live-reload]

# Secrets & environment
wrangler pages secret put <name> --project-name <name> [--env <env>]
wrangler pages secret list --project-name <name> [--env <env>]
wrangler pages secret delete <name> --project-name <name> [--env <env>]

# Logs
wrangler pages deployment tail --project-name <name> [--format json|pretty]

# Global
wrangler login
wrangler logout
wrangler whoami
wrangler --version

Key Takeaways

Install Wrangler globally with npm install -g wrangler, authenticate with wrangler login.
Use wrangler pages deploy ./build --project-name my-docs to deploy without Git.
Use wrangler pages secret put to manage environment variables and secrets per environment.
wrangler pages deployment tail streams real-time logs from your live Pages Functions.
wrangler.toml is optional for Pages but useful for local dev and binding configuration.

What's Next

Continue to Cloudflare Pages REST API to automate Pages management programmatically.

What Is Wrangler?​

Installation​

Global Install (Recommended)​

Per-Project Install (For CI/CD)​

Via Package Managers​

Authentication​

Interactive Login (Browser OAuth)​

API Token (CI/CD / Non-Interactive)​

Account ID​

Project Management Commands​

List All Pages Projects​

Create a New Pages Project​

Delete a Pages Project​

Deployment Commands​

Deploy (Direct Upload — No Git Required)​

List Deployments​

View a Specific Deployment​

Rollback to a Previous Deployment​

Local Development​

Start Local Dev Server​

Dev Server Options​

Environment Variables & Secrets​

Set Environment Variables (Non-sensitive)​

List Secrets​

Delete a Secret​

Bulk Upload from .env File​

Logs & Debugging​

Tail Real-Time Logs​

Filter Logs by Status​

wrangler.toml for Pages​

Complete Command Reference​

Key Takeaways​

What's Next​