cf deploy: build, check, deploy

Basic deployment

cf auth login

# Build and deploy a supported project
cf deploy

Run the command in the project root. You need valid authentication, the intended account, and a supported build integration. A cloudflare.config.ts file by itself is not standardized Build Output.

For a new plain Worker, cf init prepares the scaffold and integration. For an existing project, review cf migrate and your framework’s current support before changing the deployment command.

Understand the build contract

By default, deploy runs the detected build workflow and then reads the Build Output. That output contains resolved configuration and the files to upload. --prebuilt skips building; it does not convert arbitrary dist or .output folders into valid Build Output.

cf build

# Reuse the standardized output from a successful build
cf deploy --prebuilt

If your adapter only generates a normal framework bundle, investigate its Build Output integration. Do not rename a directory or point at a Nitro entrypoint and assume cf can deploy it.

Check modes and Worker selection

# Requires a build integration that supports the chosen mode
cf deploy --mode production

# Reuse output built with the same recorded mode
cf deploy --prebuilt --mode production

The prebuilt output’s recorded mode must match a requested mode. Rebuild for a different mode. --worker selects a Worker already present in the Build Output; it is not a flag for renaming a deployment on the fly.

Framework support varies. In cf 1.0.0-beta.5, the Nuxt mode issue prevents one detected Nuxt command from accepting --mode.

Secrets

# Inspect the supported options
cf deploy --help

# Use a private local JSON file; do not commit it
cf deploy --secrets-file .secrets.local.json

The current CLI exposes --secrets-file for JSON or environment-file input. Early beta discussions that say the flag does not exist refer to older versions. Review the linked upstream reports for environment-file formats and first-deployment secret behavior before relying on them.

bindings.secret() declares an expected binding. Keep values out of executable configuration and public build artifacts. The deployment script for this static website requires no Worker secrets.

Checks and previews

cf deploy --dry-run builds and validates without uploading the Worker or sending API requests; it does not need credentials. If the project has no cloudflare.config.ts, automatic configuration can still install packages and change local files first. Inspect the generated output and local behavior before a real deployment.

cf dev is local development, not a publicly accessible preview deployment. For a shareable Worker Preview, use cf previews deploy. It builds with preview context, uploads the preview, and needs credentials; the command has no --dry-run option. Preview behavior can change during the beta. Do not guess a cf deploy --preview flag.

Common failures

• Build Output missing: the build integration produced a framework bundle without the required specification.
• Mode mismatch: prebuilt output belongs to another mode or does not record a mode.
• No matching Worker: --worker does not match any Worker in the output.
• Required secret unavailable: review declaration, provisioning and the current first-deployment issue.
• Unknown binding resource: confirm the selected account and resource identifier.

Keep a working Wrangler deployment available while testing the beta. Use the command reference to compare workflows.