system-environment-variables.mdx

pcx_content_type	configuration
title	System environment variables
head
description	Local environment variables that can change Wrangler's behavior.

import { Render, Type, MetaInfo } from "~/components";

System environment variables are local environment variables that can change Wrangler's behavior. There are three ways to set system environment variables:

1. Create an .env file in your project directory. Set the values of your environment variables in your .env file. This is the recommended way to set these variables, as it persists the values between Wrangler sessions.

2. Inline the values in your Wrangler command. For example, WRANGLER_LOG="debug" npx wrangler deploy will set the value of WRANGLER_LOG to "debug" for this execution of the command.

3. Set the values in your shell environment. For example, if you are using Z shell, adding export CLOUDFLARE_API_TOKEN=... to your ~/.zshrc file will set this token as part of your shell configuration.

:::note To set different system environment variables for each environment, create files named .env.<environment-name>. When you use wrangler <command> --env <environment-name>, the corresponding environment-specific file will be loaded instead of the .env file, so the two files are not merged. :::

:::note During local development, the values in .env files are also loaded into the env object in your Worker, so you can access them in your Worker code.

For example, if you set API_HOST="localhost:3000" in your .env file, you can access it in your Worker like this:

const apiHost = env.API_HOST;

See the Environment variables and secrets page for more information on how to use .env files in local development. :::

Supported environment variables

Wrangler supports the following environment variables:

• CLOUDFLARE_ACCOUNT_ID

  • The account ID for the Workers related account.

• CLOUDFLARE_API_TOKEN

  • The API token for your Cloudflare account, can be used for authentication for situations like CI/CD, and other automation.

• CLOUDFLARE_API_KEY

  • The API key for your Cloudflare account, usually used for older authentication method with CLOUDFLARE_EMAIL=.

• CLOUDFLARE_EMAIL

  • The email address associated with your Cloudflare account, usually used for older authentication method with CLOUDFLARE_API_KEY=.

• CLOUDFLARE_ACCESS_CLIENT_ID

  • The Client ID of a Cloudflare Access Service Token, used to authenticate with Access-protected domains in non-interactive environments such as CI/CD pipelines. Must be set together with CLOUDFLARE_ACCESS_CLIENT_SECRET. When both variables are set, Wrangler authenticates using the service token instead of launching cloudflared access login.

• CLOUDFLARE_ACCESS_CLIENT_SECRET

  • The Client Secret of a Cloudflare Access Service Token, used together with CLOUDFLARE_ACCESS_CLIENT_ID to authenticate with Access-protected domains in non-interactive environments.

• CLOUDFLARE_ENV

  • The environment to use for Wrangler commands. This allows you to select an environment without using the --env flag. For example, CLOUDFLARE_ENV=production wrangler deploy will deploy to the production environment. The --env command line argument takes precedence over this environment variable.

• NODE_ENV

  • Sets the value of process.env.NODE_ENV in your Worker code. Defaults to "development" for wrangler dev and "production" for wrangler deploy and wrangler versions upload. Refer to Bundling for more information.

• WRANGLER_SEND_METRICS

  • Options for this are true and false. Defaults to true. Controls whether Wrangler can send anonymous usage data to Cloudflare for this project. You can learn more about this in our data policy.

• CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>

  • The local connection string for your database to use in local development with Hyperdrive. For example, if the binding for your Hyperdrive is named PROD_DB, this would be CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_PROD_DB="postgres://user:password@127.0.0.1:5432/testdb". Each Hyperdrive is uniquely distinguished by the binding name.

• CLOUDFLARE_API_BASE_URL

  • The default value is "https://api.cloudflare.com/client/v4".

• WRANGLER_LOG

  • Options for Logging levels are "none", "error", "warn", "info", "log" and "debug". Levels are case-insensitive and default to "log". If an invalid level is specified, Wrangler will fallback to the default. Logs can include requests to Cloudflare's API, any usage data being collected, and more verbose error logs.

• WRANGLER_LOG_PATH

  • A file or directory path where Wrangler will write debug logs. If the path ends in .log, Wrangler will consider this the path to a file where all logs will be written. Otherwise, Wrangler will treat the path as a directory where it will write one or more log files using a timestamp for the filenames.

• FORCE_COLOR

  • By setting this to 0, you can disable Wrangler's colorised output, which makes it easier to read with some terminal setups. For example, FORCE_COLOR=0.

• WRANGLER_HTTPS_KEY_PATH

  • Path to a custom HTTPS certificate key when running wrangler dev, to be used with WRANGLER_HTTPS_CERT_PATH.

• WRANGLER_HTTPS_CERT_PATH

  • Path to a custom HTTPS certificate when running wrangler dev, to be used with WRANGLER_HTTPS_KEY_PATH.

• DOCKER_HOST

  • Used for local development of Containers. Wrangler will attempt to automatically find the correct socket to use to communicate with your container engine. If that does not work (usually surfacing as an internal error when attempting to connect to your Container), you can try setting the socket path using this environment variable.

• WRANGLER_R2_SQL_AUTH_TOKEN

  • API token used for executing queries with R2 SQL.

• WRANGLER_OUTPUT_FILE_PATH

  • Specifies a file path where Wrangler will write output data in ND-JSON (newline-delimited JSON) format. Each line in the file is a separate JSON object containing information about Wrangler operations such as deployments, version uploads, and errors. This is useful for CI/CD pipelines and automation tools that need to programmatically access deployment information. If both WRANGLER_OUTPUT_FILE_PATH and WRANGLER_OUTPUT_FILE_DIRECTORY are set, WRANGLER_OUTPUT_FILE_PATH takes precedence.

• WRANGLER_OUTPUT_FILE_DIRECTORY

  • Specifies a directory where Wrangler will create a randomly-named file (format: wrangler-output-<timestamp>-<random>.json) to write output data in ND-JSON format. This is useful when you want to keep output files organized in a specific directory but do not need to control the exact filename. If both WRANGLER_OUTPUT_FILE_PATH and WRANGLER_OUTPUT_FILE_DIRECTORY are set, WRANGLER_OUTPUT_FILE_PATH takes precedence.

• WRANGLER_CACHE_DIR

  • Custom directory for Wrangler's cache files. When set, this overrides the default cache location (node_modules/.cache/wrangler). Useful for environments that do not use a traditional node_modules directory, such as Yarn PnP.

• MINIFLARE_CACHE_DIR

  • Custom directory for Miniflare's cf.json cache file, used during local development with wrangler dev. When set, this overrides the default cache location (node_modules/.mf). Useful for environments that do not use a traditional node_modules directory, such as Yarn PnP.

• CLOUDFLARE_CF_FETCH_ENABLED

  • Controls whether Miniflare fetches the cf.json file containing Request.cf properties from Cloudflare during local development. Set to "false" or "0" to disable fetching entirely and use fallback data. No node_modules/.mf/cf.json file will be created when disabled. Defaults to "true". This is particularly useful for non-JavaScript projects (such as Rust or Go Workers) that do not want a node_modules directory created automatically. The explicit cf option in the Miniflare API takes precedence over this environment variable.

• CLOUDFLARE_CF_FETCH_PATH

  • Specifies a custom path for caching the cf.json file, overriding the default node_modules/.mf/cf.json location. This is useful for multi-project setups where you want a shared cache location, or for projects that want to store the cache outside of node_modules. The explicit cf option in the Miniflare API takes precedence over this environment variable, and CLOUDFLARE_CF_FETCH_ENABLED=false takes precedence over this variable.

Example output file

When these environment variables are set, Wrangler writes one JSON object per line to the output file. Each entry includes a timestamp field and a type field indicating the kind of operation. Here is an example of what the file might contain after running wrangler deploy:

{"type":"wrangler-session","version":1,"wrangler_version":"3.78.0","command_line_args":["deploy"],"log_file_path":"/path/to/logs/wrangler-2024-11-03_12-00-00_abc.log","timestamp":"2024-11-03T12:00:00.000Z"}
{"type":"deploy","version":1,"worker_name":"my-worker","worker_tag":"abc123def456","version_id":"v1-abc123","targets":["https://my-worker.example.workers.dev"],"worker_name_overridden":false,"wrangler_environment":"production","timestamp":"2024-11-03T12:00:05.000Z"}

The wrangler-session entry is written when Wrangler starts and contains information about the command being run. The deploy entry is written when a deployment completes successfully and includes the worker name, version ID, and deployment URLs.

Other entry types include:

• version-upload - Written by wrangler versions upload with version ID and preview URLs
• version-deploy - Written by wrangler versions deploy with deployment information
• pages-deploy - Written by wrangler pages deploy with Pages deployment details
• command-failed - Written when a command fails, including error code and message

Example .env file

The following is an example .env file:

CLOUDFLARE_ACCOUNT_ID=<YOUR_ACCOUNT_ID_VALUE>
CLOUDFLARE_API_TOKEN=<YOUR_API_TOKEN_VALUE>
CLOUDFLARE_EMAIL=<YOUR_EMAIL>
WRANGLER_SEND_METRICS=true
CLOUDFLARE_API_BASE_URL=https://api.cloudflare.com/client/v4
WRANGLER_LOG=debug
WRANGLER_LOG_PATH=../Desktop/my-logs/my-log-file.log
WRANGLER_R2_SQL_AUTH_TOKEN=<YOUR_R2_API_TOKEN_VALUE>
CLOUDFLARE_CF_FETCH_ENABLED=false

Deprecated global variables

The following variables are deprecated. Use the new variables listed above to prevent any issues or unwanted messaging.

• CF_ACCOUNT_ID
• CF_API_TOKEN
• CF_API_KEY
• CF_EMAIL
• CF_API_BASE_URL