wrangler secret

The wrangler secret command manages encrypted secrets for your Cloudflare Workers.

secret put

Create or update a secret for a Worker.

wrangler secret put <key>

key

string

required

The variable name to be accessible in the Worker

Options

--name

string

Name of the Worker. If not specified, it will default to the name specified in your Wrangler config file

--env

string

Environment to use

Example

# Add a secret (interactive prompt for value)
wrangler secret put API_KEY

# Add a secret with specific worker name
wrangler secret put DATABASE_URL --name my-worker

# Add a secret for a specific environment
wrangler secret put API_TOKEN --env production

# Pipe secret value from stdin
echo "my-secret-value" | wrangler secret put API_KEY

Notes

If running in an interactive terminal, Wrangler will prompt you to enter the secret value securely
If not in an interactive terminal, the secret value is read from stdin
Secrets are encrypted and stored securely by Cloudflare
In Workers code, secrets are accessed via the env object: env.API_KEY

secret delete

Delete a secret from a Worker.

wrangler secret delete <key>

key

string

required

The variable name to be accessible in the Worker

Options

--name

string

Name of the Worker. If not specified, it will default to the name specified in your Wrangler config file

--env

string

Environment to use

Example

# Delete a secret
wrangler secret delete API_KEY

# Delete a secret from a specific worker
wrangler secret delete OLD_TOKEN --name my-worker

# Delete a secret from a specific environment
wrangler secret delete TEMP_KEY --env staging

Notes

Requires confirmation before deletion
Once deleted, the secret cannot be recovered
The Worker will no longer have access to this secret after deletion

secret list

List all secrets for a Worker.

wrangler secret list

Options

--name

string

Name of the Worker. If not specified, it will default to the name specified in your Wrangler config file

--env

string

Environment to use

--format

'json' | 'pretty'

default:"json"

The format to print the secrets in

Example

# List all secrets
wrangler secret list

# List secrets in pretty format
wrangler secret list --format pretty

# List secrets for a specific worker
wrangler secret list --name my-worker

# List secrets for a specific environment
wrangler secret list --env production --format json

Output

The list command returns secret names only (not values, as they are encrypted):

[
  {
    "name": "API_KEY"
  },
  {
    "name": "DATABASE_URL"
  },
  {
    "name": "AUTH_TOKEN"
  }
]

secret bulk

Upload multiple secrets for a Worker at once.

wrangler secret bulk [file]

file

string

The file of key-value pairs to upload, as JSON in form {"key": "value", ...} or .env file in the form KEY=VALUE. If omitted, Wrangler expects to receive input from stdin rather than a file

Options

--name

string

Name of the Worker. If not specified, it will default to the name specified in your Wrangler config file

--env

string

Environment to use

Example

# Upload secrets from JSON file
wrangler secret bulk secrets.json

# Upload secrets from .env file
wrangler secret bulk .env.production

# Upload secrets from stdin (JSON format)
echo '{"API_KEY":"abc123","DB_PASS":"secret"}' | wrangler secret bulk

# Upload secrets with specific worker and environment
wrangler secret bulk secrets.json --name my-worker --env production

File Formats

JSON Format:

secrets.json

{
  "API_KEY": "your-api-key",
  "DATABASE_URL": "postgres://...",
  "AUTH_SECRET": "very-secret-token"
}

.env Format:

.env.production

API_KEY=your-api-key
DATABASE_URL=postgres://...
AUTH_SECRET=very-secret-token

Notes

Both JSON and .env file formats are supported
Existing secrets with the same names will be updated
All other existing secrets will be preserved
The operation is atomic - either all secrets are updated or none are

Complete Workflow Example

Add individual secrets

# Add secrets interactively
wrangler secret put API_KEY
# Enter value when prompted: abc123xyz

wrangler secret put DATABASE_URL
# Enter value when prompted: postgres://user:pass@host:5432/db

Verify secrets were added

wrangler secret list --format pretty

Output:

Secret Name: API_KEY

Secret Name: DATABASE_URL

Bulk upload additional secrets

Create a secrets file:

secrets.json

{
  "STRIPE_KEY": "sk_test_...",
  "SENDGRID_API_KEY": "SG...",
  "JWT_SECRET": "super-secret"
}

Upload the secrets:

wrangler secret bulk secrets.json

Use secrets in your Worker

index.ts

export default {
  async fetch(request, env) {
    // Access secrets via the env object
    const apiKey = env.API_KEY;
    const dbUrl = env.DATABASE_URL;
    const stripeKey = env.STRIPE_KEY;
    
    // Use secrets in your application logic
    const response = await fetch('https://api.example.com', {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });
    
    return new Response('Success');
  }
};

Rotate a secret

# Update an existing secret with a new value
wrangler secret put API_KEY
# Enter new value when prompted

Clean up unused secrets

# Delete secrets that are no longer needed
wrangler secret delete OLD_API_TOKEN
# Confirm deletion when prompted

Best Practices

Never commit secrets to version control - Use .gitignore to exclude secret files
Use different secrets for different environments - Maintain separate secrets for production, staging, and development
Rotate secrets regularly - Update sensitive credentials periodically
Use bulk upload for multiple secrets - More efficient than adding secrets one by one
Store backup copies securely - Keep encrypted backups of your secrets in a secure password manager
Limit secret access - Only grant access to secrets for team members who need them

Secrets vs Environment Variables

Feature	Secrets	Environment Variables
Storage	Encrypted at rest	Plain text in config
Visibility	Hidden in dashboard	Visible in dashboard
Use case	API keys, passwords, tokens	Non-sensitive config values
Access method	`env.SECRET_NAME`	`env.VAR_NAME`
Management	`wrangler secret` commands	Wrangler config file or dashboard

When to use secrets:

API keys and tokens
Database passwords
Encryption keys
OAuth client secrets
Any sensitive credential

When to use environment variables:

Feature flags
Non-sensitive configuration
Public API endpoints
Version numbers

Essential Commands

Version Management

Storage Commands

Service Commands

Pages Commands

Configuration

secret put

Options

Example

Notes

secret delete

Options

Example

Notes

secret list

Options

Example

Output

secret bulk

Options

Example

File Formats

Notes

Complete Workflow Example

Best Practices

Secrets vs Environment Variables

Build docs developers (and LLMs) love

Essential Commands

Version Management

Storage Commands

Service Commands

Pages Commands

Configuration

​secret put

​Options

​Example

​Notes

​secret delete

​Options

​Example

​Notes

​secret list

​Options

​Example

​Output

​secret bulk

​Options

​Example

​File Formats

​Notes

​Complete Workflow Example

​Best Practices

​Secrets vs Environment Variables

Build docs developers (and LLMs) love

secret put

Options

Example

Notes

secret delete

Options

Example

Notes

secret list

Options

Example

Output

secret bulk

Options

Example

File Formats

Notes

Complete Workflow Example

Best Practices

Secrets vs Environment Variables