t1k:cloudflare
| Field | Value |
|---|---|
| Module | t1k-devops |
| Version | 4.1.3 |
| Effort | low |
| 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
How to invoke
Section titled “How to invoke”/t1k:cloudflarenew worker | migrate wrangler | d1/r2/kv/dns/secrets op | command lookupCloudflare 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.
Decision tree
Section titled “Decision tree”| Intent | Do this | Read |
|---|---|---|
| New Worker / project | cf init <dir> | config-and-migration.md (references/config-and-migration.md) |
| Deploy | cf deploy | below |
| Legacy Wrangler project | cf migrate --bundler vite [path] | config-and-migration.md (references/config-and-migration.md) |
| D1 / R2 / KV / DNS operation | cf 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 table | command-mapping.md (references/command-mapping.md) |
| New service with a UI and an API/datastore | TWO Workers from the start: UI holds no datastore or key bindings, reads via service binding | worker-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 redeploy | config-as-data.md (references/config-as-data.md) |
cf lacks a command / fails / Worker secrets | GAP: report via /t1k:issue, tell the user, never wrangler. Secrets: cf workers secrets bulk | gaps-and-no-fallback.md (references/gaps-and-no-fallback.md) |
Install and run
Section titled “Install and run”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).
Agent-facing notes
Section titled “Agent-facing notes”- JSON by default when scripted.
cftargets 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.
cfitself tells you this: running any--helpprints anAGENT COMMAND DISCOVERYbanner instructing you to usecf cli search "<task>"first rather than chaining nested--helpcalls, 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> --helpfor the exact flags. Verified working unauthenticated:cf cli search "deploy worker"returnedcf deployfirst (first run on an older beta; only the command’s existence was re-checked on the pinned one). [—help-sourced] --dry-runexists on the write-shaped commands (cf deploy,cf workers secrets update|bulk,cf migrate, and the generated API commands such ascf 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 deleteandcf kv bulk deletealso 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--forceexits 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 nocf tail(usecf o11y telemetry query); a first deploy seeds secrets withcf deploy --secrets-file;cf migrateneeds a local wrangler;cf r2 objects puttimes out on large files (~175 MB). - Global flags that matter for scripting:
-z/--zone(Zone ID or domain, overridesCLOUDFLARE_ZONE_ID),--profile(named auth profile),--local(cf dev --persist-tois 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]:
CLOUDFLARE_API_TOKENenvironment variable (an API token; this is the CI / non-interactive path; setCLOUDFLARE_ACCOUNT_IDalongside it).- 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.
Deploy
Section titled “Deploy”cf deploy # deploy the Worker in the current projectcf deploy --dry-run # build + checks only, no uploadcf 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).
Config shape
Section titled “Config shape”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]
Full references
Section titled “Full references”- config-and-migration.md (
references/config-and-migration.md) —cloudflare.config.tsshape,cf init,cf migrate(legacy Wrangler project → cf), build tooling (Vite default) - command-mapping.md (
references/command-mapping.md) — historical wrangler →cftable, D1/R2/KV write commands, UNVERIFIED rows marked - beta-caveats-and-fallback.md (
references/beta-caveats-and-fallback.md) — beta status, thecf-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 whencflacks a command; verifiedcffacts (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:DigestStreamshape, deploy replacing envvars, cross-env Durable Objectscript_namecoupling