Cloudflare Workers · Wrangler · all subjects

wrangler/environments

44 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Environment creates new Worker with appended name

When you create an environment, Cloudflare creates a new Worker with the name format <top-level-name>-<environment-name>. For example, a Worker project named 'my-worker' with an environment 'dev' deploys as a Worker named 'my-worker-dev'.

SSL certificates are public record for environment-named Workers

When a Worker is created via an environment, Cloudflare automatically creates an SSL certificate for it. SSL certifications are discoverable and a matter of public record. Be careful when naming environments to avoid sensitive information in the name, such as 'migrating-service-from-company1-to-company2' or 'company1-acquisition-load-test'.

CF_ZONE_ID environment variable

CF_ZONE_ID is an environment variable that specifies or overrides the target Zone ID for Wrangler commands.

Wrangler v1 preferred CI authentication method

Using environment variables is the preferred method for using Wrangler in CI (continuous integration) environments.

CF_API_KEY environment variable

CF_API_KEY is an environment variable that specifies your Cloudflare Global API Key for Wrangler authentication. It can be used as an alternative to CF_API_TOKEN when paired with CF_EMAIL.

CF_API_TOKEN environment variable

CF_API_TOKEN is an environment variable that specifies your Cloudflare API token for Wrangler authentication. When used with CF_ACCOUNT_ID, it overrides default credentials stored in wrangler config or your Wrangler file.

CF_EMAIL environment variable

CF_EMAIL is an environment variable that specifies your Cloudflare email address for Wrangler authentication. It can be used as an alternative to CF_API_TOKEN when paired with CF_API_KEY.

Environment variables override stored credentials in Wrangler v1

Defining environment variables inline (CF_ACCOUNT_ID, CF_API_TOKEN, CF_EMAIL, CF_API_KEY, or CF_ZONE_ID) will override the default credentials stored in wrangler config or in your Wrangler file.

CF_ACCOUNT_ID environment variable

CF_ACCOUNT_ID is an environment variable that specifies your Cloudflare account ID for Wrangler authentication. It can be obtained from the Cloudflare dashboard in Overview and overrides default credentials.

Environment configuration in Wrangler v1

Environment-specific configuration is specified under an [env.name] section in the Wrangler file. Environment configuration values override top-level configuration values. Environments are deployed using the --env or -e flag with commands: build, dev, preview, publish, and secret. Some environment properties can be inherited from top-level configuration.

Wrangler environment variables via CF_ prefix

Wrangler supports passing configuration file keys as environment variables using the `CF_` prefix followed by the uppercased TOML key name. Example: `CF_NAME=my-worker CF_ACCOUNT_ID=1234 wrangler dev`.

Using different webpack configs per environment

You can use different webpack configuration files for different Wrangler environments. Specify 'webpack_config' in the root of wrangler.toml for the default environment, and override it in each environment's section under 'env'. For example, use webpack.development.js for development, webpack.staging.js for staging, and webpack.production.js for production.

WRANGLER_SEND_METRICS environment variable

WRANGLER_SEND_METRICS is a boolean environment variable (optional) with options true and false. Defaults to true. It controls whether Wrangler can send anonymous usage data to Cloudflare for this project.

WRANGLER_SEND_ERROR_REPORTS environment variable

WRANGLER_SEND_ERROR_REPORTS is a boolean environment variable (optional) with options true and false. Defaults to undefined. It controls whether Wrangler can send non-user error reports to Cloudflare for this project. If undefined, Wrangler will ask the user whether to send an error report each time there is a non-user error.

CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME> environment variable

CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME> is a string environment variable (optional) that specifies 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 environment variable

CLOUDFLARE_API_BASE_URL is a string environment variable (optional). The default value is "https://api.cloudflare.com/client/v4".

WRANGLER_LOG environment variable

WRANGLER_LOG is a string environment variable (optional) that sets the logging level. 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 environment variable

WRANGLER_LOG_PATH is a string environment variable (optional) that specifies 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.

WRANGLER_LOG_SANITIZE environment variable

WRANGLER_LOG_SANITIZE is a boolean environment variable (optional) with options true and false. Defaults to true. It controls whether Wrangler will sanitize any sensitive information from logs written to the console or to a log file. Sensitive information includes API tokens, email addresses, account IDs, and more.

FORCE_COLOR environment variable

FORCE_COLOR is a string environment variable (optional). 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 and WRANGLER_HTTPS_CERT_PATH environment variables

WRANGLER_HTTPS_KEY_PATH and WRANGLER_HTTPS_CERT_PATH are string environment variables (optional) that specify paths to custom HTTPS certificate key and certificate respectively when running wrangler dev. These are used together.

DOCKER_HOST environment variable

DOCKER_HOST is a string environment variable (optional) 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_OUTPUT_FILE_PATH environment variable

WRANGLER_OUTPUT_FILE_PATH is a string environment variable (optional) that 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 environment variable

WRANGLER_OUTPUT_FILE_DIRECTORY is a string environment variable (optional) that 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 environment variable

WRANGLER_CACHE_DIR is a string environment variable (optional) that specifies a 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 environment variable

MINIFLARE_CACHE_DIR is a string environment variable (optional) that specifies a 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 environment variable

CLOUDFLARE_CF_FETCH_ENABLED is a string environment variable (optional) that 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 environment variable

CLOUDFLARE_CF_FETCH_PATH is a string environment variable (optional) that 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.

Wrangler output file format with ND-JSON

When WRANGLER_OUTPUT_FILE_PATH or WRANGLER_OUTPUT_FILE_DIRECTORY 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. The wrangler-session entry is written when Wrangler starts and contains information about the command being run. Other entry types include: deploy (written when a deployment completes successfully), version-upload (written by wrangler versions upload), version-deploy (written by wrangler versions deploy), pages-deploy (written by wrangler pages deploy), and command-failed (written when a command fails).

Example Wrangler output file entries

Example output file entries 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"}

Deprecated global environment variables

The following variables are deprecated and should no longer be used: CF_ACCOUNT_ID, CF_API_TOKEN, CF_API_KEY, CF_EMAIL, CF_API_BASE_URL. Use the new variables with CLOUDFLARE_ or WRANGLER_ prefixes to prevent any issues or unwanted messaging.

WRANGLER_R2_SQL_AUTH_TOKEN environment variable

WRANGLER_R2_SQL_AUTH_TOKEN is a string environment variable (optional) that provides the API token used for executing queries with R2 SQL.

System environment variables overview

System environment variables are local environment variables that can change Wrangler's behavior. They can be set in three ways: by creating an .env file in the project directory (recommended), by inlining values in the Wrangler command (e.g., WRANGLER_LOG="debug" npx wrangler deploy), or by setting them in the shell environment.

.env files for different environments

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. The two files are not merged.

Environment variables loaded into Worker env object during local development

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;

CLOUDFLARE_ACCOUNT_ID environment variable

CLOUDFLARE_ACCOUNT_ID is a string environment variable (optional) that specifies the account ID for the Workers related account.

CLOUDFLARE_API_TOKEN environment variable

CLOUDFLARE_API_TOKEN is a string environment variable (optional) that provides the API token for your Cloudflare account. It can be used for authentication in situations like CI/CD and other automation.

CLOUDFLARE_API_KEY environment variable

CLOUDFLARE_API_KEY is a string environment variable (optional) that provides the API key for your Cloudflare account. It is usually used for the older authentication method with CLOUDFLARE_EMAIL.

CLOUDFLARE_EMAIL environment variable

CLOUDFLARE_EMAIL is a string environment variable (optional) that specifies the email address associated with your Cloudflare account. It is usually used for the older authentication method with CLOUDFLARE_API_KEY.

CLOUDFLARE_ACCESS_CLIENT_ID and CLOUDFLARE_ACCESS_CLIENT_SECRET environment variables

CLOUDFLARE_ACCESS_CLIENT_ID and CLOUDFLARE_ACCESS_CLIENT_SECRET are string environment variables (optional) that provide the Client ID and Client Secret of a Cloudflare Access Service Token. They are used to authenticate with Access-protected domains in non-interactive environments such as CI/CD pipelines. Both variables must be set together. When both are set, Wrangler authenticates using the service token instead of launching cloudflared access login.

CLOUDFLARE_AUTH_USE_KEYRING environment variable

CLOUDFLARE_AUTH_USE_KEYRING is a boolean environment variable (optional) with options true and false. Defaults to unset. It overrides the persistent preference set by wrangler login --use-keyring / --no-use-keyring for a single invocation. When true, Wrangler stores OAuth credentials in an encrypted file with the encryption key held in the OS keychain, and exits with an error if the keychain backend is unavailable. When false, Wrangler uses the legacy plaintext TOML file even if the persistent preference is enabled.

CLOUDFLARE_ENV environment variable

CLOUDFLARE_ENV is a string environment variable (optional) that specifies 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 environment variable

NODE_ENV is a string environment variable (optional) that 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.

Environment overrides and field inheritance

The env key in wrangler config supports per-environment config overrides. Some fields inherit from the top level while others must be redeclared in each environment. The schema should be consulted for inheritance rules rather than assuming which fields inherit.

Give your agent this brain