Skip to content

Cloudflare CLI

Jump to bottom
Serge Gatezh edited this page Oct 8, 2026 · 1 revision

Cloudflare CLI (cf)

cf is Cloudflare's successor to Wrangler. It covers the whole Cloudflare API (about 2,900 commands, compared with about 280 in Wrangler) and replaces wrangler.jsonc with a typed cloudflare.config.ts. This page covers what applies across images: which ones can run it, when a project should switch, and how credentials work in a container. Setup inside claude-code is in its README.

Which images can run it

cf needs Node.js 22.18 or later, and it doesn't support Bun: when cf runs on Bun, every command that loads cloudflare.config.ts fails.

Image cf
claude-code, claude-code-sandbox Preinstalled, pinned and bumped by Renovate, telemetry off, zsh completion set up
hugo-bun-node Not preinstalled. Node 24 is there, so npm install -g cf works. See the README
ralphex-fe Not preinstalled. Node 24 is there
bun, hugo-bun, claude-bun Can't run it: no Node

cf or Wrangler, per project

The project has Use
cloudflare.config.ts cf
wrangler.jsonc, wrangler.json or wrangler.toml, and no cloudflare.config.ts Wrangler, until the project is migrated
Neither (account work: DNS, zones, D1, R2…) cf

Don't run cf dev, cf build or cf deploy in a project that is still on Wrangler. They generate a new configuration that ignores wrangler.jsonc. Without a terminal, which is how agents and CI run, they rewrite package.json, the lockfile, .gitignore and vite.config.ts without asking. Migrate first.

The two tools share nothing:

Wrangler cf
Project config wrangler.jsonc / .toml cloudflare.config.ts
Environments env blocks, --env modes, --mode
Login wrangler login cf auth login, which doesn't reuse a Wrangler login
Resources Accepts names Expects IDs, e.g. cf d1 query <DATABASE_ID>
Output Tables JSON on stdout, messages on stderr

Neither tool reads the other's config. A migrated project that still needs a Wrangler-only command keeps both files.

When to migrate

  • Wrangler isn't deprecated yet. When the cf beta ends, Cloudflare will ship a final Wrangler major that points to cf, then maintain Wrangler for 18 more months. No end date for the beta had been announced as of the date below.
  • Some tasks still need Wrangler: live logs (wrangler tail) and setting a single secret.
  • cf migrate leaves manual work: Durable Object migrations, Workflows, Containers and package scripts, each marked with a TODO(@cloudflare) comment. The build fails until they're resolved.
  • Some Workers still build with Wrangler under the hood: JavaScript Workers built with esbuild, plus Rust and Python Workers. cf hands their dev and deploy to Wrangler.

The steps are in the claude-code README: Recommended: migrate Workers projects to cloudflare.config.ts. In short: cf migrate --dry-run, then cf migrate, then resolve the TODOs. Migration also adds cf as a dev dependency, and from then on the global cf runs the project's copy.

Credentials in a container

cf uses the first credential it finds:

  1. CLOUDFLARE_API_TOKEN in the environment, or in a .env file in the current directory
  2. a profile chosen with --profile
  3. a profile bound to the directory with cf auth activate
  4. the default profile from cf auth login

Things that catch people out:

  • A project .env beats your login. If the project's .env sets CLOUDFLARE_API_TOKEN, cf uses that token instead of your login, without saying so. It reads only .env, not .env.local or .env.<mode>.
  • Sign-in inside a container needs --no-browser. cf auth login --no-browser prints a link and a code to approve in your host browser.
  • The login lives in ~/.config/cloudflare. Without a volume there, a rebuild signs you out. The claude-code templates mount one.
  • Use a scoped token for agents and CI. Create an API token limited to what the job needs, and set it with CLOUDFLARE_ACCOUNT_ID. This matters most in claude-code-sandbox, which shares the default variant's login and where Claude Code may run with permission prompts skipped.
  • Firewalled containers need two domains: dash.cloudflare.com for sign-in (OAuth device flow) and api.cloudflare.com for everything else. Nothing else is required while telemetry is off.

Agents

In claude-code, managed settings give every Claude Code session the per-project rule above. They also make it ask before any cf command with --force or -f. Without a terminal, cf aborts deletes unless they carry that flag, so this is the one prompt that guards destructive Cloudflare calls. Details are in the README.

Cloudflare's cloudflare plugin stays alongside cf. Its wrangler skill applies the same rule when it loads, and its MCP server searches current Cloudflare docs, which cf doesn't do.

To find a command, run cf cli search "<task>". It runs locally and needs no credentials. Add --dry-run to see a request without sending it.

Sources

Last verified: 2026-10-08, against cf 1.0.0-beta.13

Home

Using the images

Maintaining the repo

Repository · Issues · Packages

Clone this wiki locally