Skip to content

t1k:cloudflare

FieldValue
Modulet1k-devops
Version4.1.3
Effortlow
Tools—

Keywords: bindings.text, cf cli, cf d1, cf deploy, cf init, cf migrate, cf workers secrets, cloudflare cli, cloudflare dns, cloudflare kv, cloudflare workers deploy, cloudflare zone, cloudflare.config.ts, deployments.json, worker var, wrangler migrate, wrangler retired, wrangler.jsonc, wrangler.toml

/t1k:cloudflare
new worker | migrate wrangler | d1/r2/kv/dns/secrets op | command lookup

Cloudflare CLI (cf) — the ONLY Cloudflare CLI

Section titled “Cloudflare CLI (cf) — the ONLY Cloudflare CLI”

Cloudflare’s own CLI (npm package cf, repo cloudflare/cf, binary cf) is the only Cloudflare CLI the studio uses. wrangler is retired (studio decision 2026-10-07): not a fallback, never run it — cf-only-guard.cjs denies it. If cf lacks a command or fails, that is a gap to report (gaps-and-no-fallback.md (references/gaps-and-no-fallback.md)), not a reason to reach for wrangler. cf is in open beta (pinned version: the cf-pin line in beta-caveats-and-fallback.md (references/beta-caveats-and-fallback.md)).

Apply when: scaffolding a new Worker, deploying, running a D1/R2/KV/DNS/zone/secrets operation, migrating a legacy Wrangler project, or looking up a command you don’t know the shape of. Cost-review a D1/R2 design (row-billed write/scan cost, aggregate-then-write) is a different concern — that’s t1k-datastore-cost, drive both together on a datastore change.

IntentDo thisRead
New Worker / projectcf init <dir>config-and-migration.md (references/config-and-migration.md)
Deploycf deploybelow
Legacy Wrangler projectcf migrate --bundler vite [path]config-and-migration.md (references/config-and-migration.md)
D1 / R2 / KV / DNS operationcf d1 … / cf r2 … / cf kv … / cf dns …command-mapping.md (references/command-mapping.md)
“what’s the cf equivalent of wrangler X?”cf cli search "<task>", or the historical mapping tablecommand-mapping.md (references/command-mapping.md)
New service with a UI and an API/datastoreTWO Workers from the start: UI holds no datastore or key bindings, reads via service bindingworker-architecture-defaults.md (references/worker-architecture-defaults.md)
A value that changes as the product grows (consumers, audiences, allow-lists, flags, tenants)A D1 table read at request time with a short cache and an audited write path — never a var whose only effect is the next redeployconfig-as-data.md (references/config-as-data.md)
cf lacks a command / fails / Worker secretsGAP: report via /t1k:issue, tell the user, never wrangler. Secrets: cf workers secrets bulkgaps-and-no-fallback.md (references/gaps-and-no-fallback.md)

No global install needed for a one-off — bunx cf@<pin> <command> (<pin> = the cf-pin version in beta-caveats-and-fallback.md (references/beta-caveats-and-fallback.md), the single source of truth for the version) runs it without touching global npm state. A project has cf as a pinned devDependency (cf init writes one, cf migrate --install adds one), and CI/deploy workflows install that cf, never wrangler. Pin the beta version explicitly until cf leaves beta — an unpinned bunx cf can silently jump a breaking beta bump. [—help-sourced]

Runtime: cf runs on Node 22.18+; Bun is unsupported. Bun may install it; bunx cf@<pin> keeps its #!/usr/bin/env node shebang on Node only while a node is on PATH. With none (a Bun-only container), Bun’s built-in shim runs cf on Bun and the commands that load cloudflare.config.ts fail (measured 2026-11-04, Bun 1.4.3). A CI job that calls cf sets up Node 26 (studio policy; Cloudflare’s floor is 22.18+) next to Bun. Only config-loading commands break: deploy --prebuilt ran fine under bun --bun x --no-install cf in theonekit-docs (run 41775085033), the accepted form where setup-node is unavailable (kits).

  • JSON by default when scripted. cf targets both humans and agents; treat its output as machine-readable and avoid parsing prose. [blog-sourced]
  • Discovery is a search, not a —help tree-walk. cf itself tells you this: running any --help prints an AGENT COMMAND DISCOVERY banner instructing you to use cf cli search "<task>" first rather than chaining nested --help calls, and to keep the query anonymous (action + resource type only — no names, emails, domains, account/resource IDs, or tokens). It returns five compact JSON matches; run <match> --help for the exact flags. Verified working unauthenticated: cf cli search "deploy worker" returned cf deploy first (first run on an older beta; only the command’s existence was re-checked on the pinned one). [—help-sourced]
  • --dry-run exists on the write-shaped commands (cf deploy, cf workers secrets update|bulk, cf migrate, and the generated API commands such as cf d1 query|create|delete, cf r2 objects put, cf kv keys put, cf kv bulk put|delete) — use it to preview before a real write. cf d1 delete and cf kv bulk delete also take -f/--force (skip the confirmation prompt) — never pass it from an agent session; since beta.15 a destructive command without a terminal and without --force exits 1 instead of reporting success. [—help-sourced + changelog-sourced]
  • Gaps seen in practice (details in gaps-and-no-fallback.md (references/gaps-and-no-fallback.md)): debugging a live Worker has no cf tail (use cf o11y telemetry query); a first deploy seeds secrets with cf deploy --secrets-file; cf migrate needs a local wrangler; cf r2 objects put times out on large files (~175 MB).
  • Global flags that matter for scripting: -z/--zone (Zone ID or domain, overrides CLOUDFLARE_ZONE_ID), --profile (named auth profile), --local (cf dev --persist-to is rejected since beta.15) (local resource simulation instead of the real account — prefer this for anything exploratory). [—help-sourced]

Auth — non-interactive path documented; valid-token end-to-end NOT yet proven

Section titled “Auth — non-interactive path documented; valid-token end-to-end NOT yet proven”

Credential resolution order, from the package README (the cf npm package’s own docs) [README-sourced]:

  1. CLOUDFLARE_API_TOKEN environment variable (an API token; this is the CI / non-interactive path; set CLOUDFLARE_ACCOUNT_ID alongside it).
  2. The OAuth profile chosen by --profile, the nearest directory binding (cf auth activate <name> [dir]), or the default profile (refreshed automatically; stored under ~/.config/cloudflare/config/).

Also honored: CLOUDFLARE_ACCOUNT_ID (skips the account lookup), CLOUDFLARE_ZONE_ID (default zone), and CLOUDFLARE_ACCESS_CLIENT_ID/CLOUDFLARE_ACCESS_CLIENT_SECRET (Access service token); CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_ZONE_ID may also come from .env, .env.local (and .env.<mode>) files, the real process environment wins. [source-sourced: cf dist strings + the upstream changelog]

Verified on the pinned version by running cf auth whoami read-only: with a dummy value in CLOUDFLARE_API_TOKEN it reports authSource: "CLOUDFLARE_API_TOKEN environment variable" (so the env var takes precedence over a stored OAuth profile), and without it authSource names the stored OAuth profile file. Still UNVERIFIED: a REAL, valid scoped token driving a command end to end — no read-only Cloudflare token was readable from the studio vault when this was checked (cf-analytics-token returned 404/no grant), so the happy path was not exercised. Before wiring a CI credential, run cf auth whoami with the real token in a throwaway job and confirm tokenValid: true.

Interactive commands: cf auth login (OAuth device flow by default; --no-device for the localhost callback, --scopes, -f/--force), cf auth create <name>, cf auth activate <name> [dir], cf auth deactivate [dir], cf auth list, cf auth delete <name>, cf auth logout, cf auth whoami [—help-sourced]. Never run login/create or a mutating command against a real account from an agent session without the human present. Print no token value; cf auth whoami output lists account ids and OAuth scopes, so do not paste it verbatim into issues or PRs.

Terminal window
cf deploy # deploy the Worker in the current project
cf deploy --dry-run # build + checks only, no upload
cf deploy --no-provision # deploy the Worker only; never create bindings as a side effect

[—help-sourced] provision defaults to true, so a bare deploy also creates the D1/R2/KV resources its bindings need: pass --no-provision unless creating them is the intent. A clean --dry-run is NOT proof a D1 database exists (an all-zero or PLACEHOLDER- database_id passes), and cf resolves its dev server and deploys only from a standalone project, not an npm workspace root: see gaps-and-no-fallback.md (references/gaps-and-no-fallback.md) § “Workspaces, provisioning and dry-run fidelity”. A NEW Worker: create its placeholder with cf deploy (never the script API), then set required secrets, then deploy. Deploy conflicts and required-secret errors: incident-history.md (references/incident-history.md).

TypeScript cloudflare.config.ts (legacy wrangler.toml/wrangler.jsonc is migrated, not kept) — see config-and-migration.md (references/config-and-migration.md) for the defineConfig({ worker }) shape (bindings under worker.env, triggers array) and the cf init / cf migrate flows. [scaffold-verified for defineConfig({ worker: { name, compatibilityDate, entrypoint, env } }) and bindings.text() only; other builders and triggers are types-sourced, see config-and-migration.md]

  • config-and-migration.md (references/config-and-migration.md) — cloudflare.config.ts shape, cf init, cf migrate (legacy Wrangler project → cf), build tooling (Vite default)
  • command-mapping.md (references/command-mapping.md) — historical wrangler → cf table, D1/R2/KV write commands, UNVERIFIED rows marked
  • beta-caveats-and-fallback.md (references/beta-caveats-and-fallback.md) — beta status, the cf-pin (SSOT for the version), auth/install facts. Despite the filename there is NO wrangler fallback
  • gaps-and-no-fallback.md (references/gaps-and-no-fallback.md) — what to do when cf lacks a command; verified cf facts (secrets, discovery, auth, --dry-run)
  • hosted-service-auth.md (references/hosted-service-auth.md) — auth for NEW hosted services: studio-auth is MANDATORY for internal tools and services (docs/studio-auth.md; never customer-facing); no new Cloudflare Access app; Access is legacy
  • worker-architecture-defaults.md (references/worker-architecture-defaults.md) — UI and API are separate Workers by default (UI gets no datastore or key bindings)
  • config-as-data.md (references/config-as-data.md) — growth-driven values (allowed consumers, audiences, OIDC caller pins, allow-lists, flags, tenants) live in a D1 table with an audited write path, not in env + redeploy; env keeps secrets, keys, the DB binding and the issuer root of trust. Full reference: docs/config-as-data-not-env.md
  • incident-history.md (references/incident-history.md) — Gotchas: DigestStream shape, deploy replacing env vars, cross-env Durable Object script_name coupling