cf
Skill19 starsChanged 18 days agoApache-2.0View on GitHub
USE WHEN: running, finding, or troubleshooting Cloudflare CLI (`cf`) commands in this repo - dev servers, builds and their Build Output, `Env` types, startup profiling, production profiles, Workers Issues, and telemetry, local KV/D1/R2 data, the commands that still need Wrangler, or the cf equivalent of a Wrangler habit. DO NOT USE WHEN: editing application code.
- Reads credentials
In this repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/skills/vercel-react-best-practices/AGENTS.mdAGENTS.md
- hooks/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- hooks/CLAUDE.mdCLAUDE.md
- .cursor/rules/backend/hono-gateway.mdcCursor rule
- .cursor/rules/backend/ports.mdcCursor rule
- .cursor/rules/backend/service-bindings.mdcCursor rule
- .cursor/rules/backend/workers-cache.mdcCursor rule
- .cursor/rules/backend/workers-config.mdcCursor rule
- .cursor/rules/contracts/contracts.mdcCursor rule
- .cursor/rules/core/agent-instructions.mdcCursor rule
- .cursor/rules/core/boundaries.mdcCursor rule
- .cursor/rules/core/guardrails.mdcCursor rule
- .cursor/rules/core/turborepo.mdcCursor rule
- .cursor/rules/core/worktrees.mdcCursor rule
- .cursor/rules/frontend/react.mdcCursor rule
- .cursor/rules/frontend/tailwind.mdcCursor rule
- .cursor/rules/frontend/tanstack-query.mdcCursor rule
- .cursor/rules/frontend/tanstack-router.mdcCursor rule
- .cursor/rules/frontend/vite-config.mdcCursor rule
- .cursor/rules/ops/cd.mdcCursor rule
- .cursor/rules/ops/changesets.mdcCursor rule
- .cursor/rules/ops/ci.mdcCursor rule
- .cursor/rules/ops/previews.mdcCursor rule
- .cursor/rules/ops/quality-report.mdcCursor rule
- .cursor/rules/ops/release.mdcCursor rule
- .cursor/rules/quality/code-style.mdcCursor rule
- .cursor/rules/quality/comments.mdcCursor rule
- .cursor/rules/quality/knip.mdcCursor rule
- .cursor/rules/quality/lint-config.mdcCursor rule
- .cursor/rules/quality/markdown-style.mdcCursor rule
- .cursor/rules/quality/naming.mdcCursor rule
- .cursor/rules/quality/reporting.mdcCursor rule
- .cursor/rules/quality/simplicity.mdcCursor rule
- .cursor/rules/quality/testing.mdcCursor rule
- .cursor/rules/quality/typescript-config.mdcCursor rule
- .cursor/rules/tests/front-react.mdcCursor rule
- .cursor/rules/tests/hono-workers.mdcCursor rule
- changesetSkill
- front-vitestSkill
- git-commitSkill
- honoSkill
- monorepo-agent-setupSkill
- pnpmSkill
- react-doctorSkill
- reviewSkill
- review-stackSkill
- run-appSkill
- security-auditSkill
- skills-updateSkill
- tanstack-configSkill
- tanstack-querySkill
- tanstack-routerSkill
- turborepoSkill
- ui-ux-design-best-practicesSkill
- vercel-react-best-practicesSkill
- workers-best-practicesSkill
- skills-updateSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
Run from the repo root; each script runs in its app directory, next to cloudflare.config.ts.
- Very specific: line 43
Every --prebuilt command passes exactly the mode config.json records.
- Very specific: line 68
Run cf dev, cf build, cf deploy, or cf init in a directory without cloudflare.config.ts (autoconfiguration rewrites the project), or cf …
- Very specific: line 77
Every apps/front-app/.env* file holds public VITE_* values only, and the sandbox reads them through the /apps/front-app/.env* allow, …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Cloudflare CLI (cf)
cf (exact catalog pin) replaces Wrangler for dev, build, types, and deploy. Each app is configured by a typed apps/<app>/cloudflare.config.ts and built through the Cloudflare Vite plugin 2.0 beta (apps/<app>/vite.config.ts). cf is a devDependency of the root and of each app: run it through the package scripts or pnpm --filter=<app> exec cf …, never a global install. The beta changes between releases, so the installed --help beats memory and these notes.
Find the command
pnpm exec cf cli search "<task>"- local search, top 5 matches as JSON. Describe the action and the resource type (list kv keys,apply d1 migrations), never names, IDs, domains, or tokens: the query travels with telemetry when telemetry is on. For a Cloudflare docs page,pnpm exec cf docs search "<question>"returns ranked URLs as JSON under the same anonymous-query rule.pnpm exec cf schema <command words>- the API request a generated command sends (pnpm exec cf schema d1 raw).pnpm exec cf <command words> --help- flags at the installed version.--forceis sometimes an API parameter rather than a confirmation skip: read the help before passing it.--dry-runwhere the help lists it - prints the request, or builds and checks without uploading.- Run it.
Project commands
Run from the repo root; each script runs in its app directory, next to cloudflare.config.ts.
| Task | Command | Notes |
| Dev server | pnpm --filter=<app> dev (cf dev) | Runs Vite and forwards only --mode; ports stay in vite.config.ts (rule backend/ports). Background task and readiness: skill run-app |
| Build | pnpm turbo run build --filter=<app> (cf build) | Production mode; writes .cloudflare/output/v0/ |
Env types | pnpm types (cf workers types, worker-api) | The turbo types task also runs before check-types; front-app has type generation off |
| Startup profile | pnpm --filter=worker-api exec cf workers check --prebuilt --mode production, after a build | JSON bundle size and startup timings; writes worker-startup.cpuprofile (gitignored). Needs a Worker entrypoint, so not front-app |
| Deploy, upload | pnpm run deploy, pnpm run upload | Humans and CD only |
Production (read-only)
Allowed during a production investigation the user asked for; hand the command over when the sandbox or a missing cf auth login blocks it. Run pnpm exec cf … from the root: in an app directory cf reads the app's .env, which the sandbox denies.
- Profile: take the serving
version_idfrom the first entry ofcf workers deployments list --worker <app>-production, neverlatest(CD uploads and Previews create newer versions that serve nothing). Thencf workers versions profile <version-id> --worker-id <app>-production --duration-ms 10000 --profile-type cpu > "$TMPDIR/<app>.pprof", orheapfor allocations in the window (not retained memory). The version needs live traffic during the capture. - Read:
GOCACHE="$TMPDIR/go-build" go tool pprof -top -nodecount=30 <file>(the sandbox denies Go's default cache). Check what is believed off:sentryMiddlewarestays registered whenSENTRY_DSNis empty. - Telemetry: the
cloudflare-apiMCP (read scopes only) first; without its OAuth (routines, CI):cf o11y issues list --service <app>-production,cf o11y issues occurrences <issue-id>,cf o11y telemetry query --body '<json>'.
Modes and Build Output
cf devruns modedevelopment;cf buildandcf deployrunproductionunless given--mode staging; the Workers Vitest pool loadstest; a Preview build isctx.isPreviewunderproduction. Any other mode throws incloudflare.config.ts.- Select a mode with
--mode, never Wrangler's--env. - Build Output, per app under
.cloudflare/output/v0/:config.json(recordsbuildContext.modeandisPreview),workers/default/worker.config.json,workers/default/bundle/(the Worker plus its.mapfiles, uploaded as source maps),workers/default/assets/(the client build). - Every
--prebuiltcommand passes exactly the modeconfig.jsonrecords; a mismatch fails ("The Build Output was created with mode …"). Preview output deploys only throughcf previews deploy --prebuilt. .cloudflare/**(Build Output,types/, local devstate/) is generated and gitignored, and the edit hook blocks hand edits. Changecloudflare.config.tsor the source, then rebuild or runpnpm types.
Types
.cloudflare/types/index.d.ts declares the global Env and Cloudflare.Env, inferred from the whole cloudflare.config.ts default export, plus workerd runtime types. After changing cloudflare.config.ts: pnpm types, then pnpm check-types. Keep one env shape across modes and a single return in the factory: a union of shapes breaks the generated interface Env. If the config fails to load, look for a value import of a @repo/* package other than @repo/enums-common, or an extensionless relative import added inside @repo/enums-common: Node loads the file natively and adds no extensions.
Local data
--localruns a command against a short-lived Miniflare instead of the account: KV keys (cf kv keys …), D1 (cf d1 raw,cf d1 migrations list|apply), R2 objects (cf r2 objects …). A command with no local equivalent errors instead of falling through to the account.--localdefaults tostate/under cf's global config directory, which is neither the app's dev state nor writable in the Claude Code sandbox. To use whatcf devwrote, run it from the app with--persist-to .cloudflare/state:pnpm --filter=<app> exec cf kv keys list … --local --persist-to .cloudflare/state.- Resource commands take API IDs (a D1 database ID, not its name).
- While
cf devruns, the Local Explorer API answers onhttp://localhost:8700/cdn-cgi/local/explorer/api(:5174for front-app); trace and log queries: skillrun-app.
Output and exit codes
- Results are JSON on stdout, except binary and text responses (an R2 object body), which are written raw; progress, messages, and errors go to stderr. Parse stdout only, under
NO_COLOR=1: cf colors its JSON whenFORCE_COLORis set, even on a pipe, which is whydeploy-previews.shrunscf previews deploythat way. - In a non-interactive session a destructive command without
--forceexits 1 instead of prompting. cf workers versions createprints no JSON yet (upstream bugversions-upload-no-json-output): withWRANGLER_OUTPUT_FILE_PATH=<file>it appends an ND-JSONversion-uploadrecord (worker_name,version_id,preview_url) there, which CD reads. There is no--strictflag because cf always uploads strict: in CI a conflict (dashboard edits, remote-secret overrides) aborts with exit 1 andversion_id: null, and the error's hint to remove--strictdoes not apply.cf deploy --prebuilt --mode production --dry-runneeds no token and no account ID: it validates Build Output and prints the bindings it would deploy.
Never, as an agent
- Deploy, upload, promote, roll back, or preview:
pnpm run deploy,pnpm run upload,pnpm preview:*,cf deploy,cf workers versions create,cf workers deployments create,cf workers triggers deploy,cf previews deploy,cf previews delete. CD and the Previews workflow own them (rulesops/cd,ops/previews,ops/release); hand the exact command to the user. - Log in:
cf auth login(root scriptlogin:cloudflare) is the user's. cf readsCLOUDFLARE_API_TOKEN/CLOUDFLARE_ACCOUNT_IDlike Wrangler did;CF_ACCOUNT_IDis a deprecated alias. - Run
cf dev,cf build,cf deploy, orcf initin a directory withoutcloudflare.config.ts(autoconfiguration rewrites the project), orcf migrateanywhere (it rewrites a Wrangler project's files for cf). A new app copies an existing app'scloudflare.config.tsandvite.config.ts, then is adapted by hand. - Change account state without
--local- a KV, D1, or R2 write or delete,cf workers secrets update|delete|bulk,cf workers delete- unless the user asked for that exact operation and its--dry-runmatched.
For the hand-off: promote or roll back with pnpm --filter=<app> exec cf workers deployments create --worker <app>-production --strategy percentage --versions '[{"version_id":"<id>","percentage":100}]' (earlier ids: cf workers deployments list --worker <app>-production); after the first production deploy, or when a Preview has no URL, pnpm --filter=<app> exec cf workers triggers deploy --mode production applies previewUrls and workers.dev once per app.
Secrets
- Local values come from a gitignored Worker
.envor the shell (SENTRY_DSN=… pnpm dev; turbo passesSENTRY_DSNtoworker-api#dev), never a.dev.vars; unset means Sentry is off in dev. The Vite plugin aborts on an env file it cannot read and the agent sandbox denies**/.env, so the agent session setsSKIP_ENV_FILES=1and sandboxed runs skip the.env(rulebackend/workers-config). - Deployed secrets are declared with
bindings.secret(); thetestmode and Previews usebindings.text("")forSENTRY_DSN. Values go up with--secrets-file <path>oncf deploy/cf workers versions create(a JSON file outside the checkout, e.g. under$TMPDIR, deleted after use: a dotenv file expands$VARand yields to a same-named process environment variable, even an empty one), or one at a time withread -rs V && pnpm --filter=<app> exec cf workers secrets update <NAME> --worker <app>-production --type secret_text --text "$V"; unset V, which keeps the value out of shell history - users and CD only. - Every
apps/front-app/.env*file holds publicVITE_*values only, and the sandbox reads them through the**/apps/front-app/.env*allow, becausebuildhashes them as inputs.
Still Wrangler
The root devDependency wrangler stays for what cf lacks. Run it as pnpm exec wrangler …; each row needs the user's Wrangler credentials (pnpm exec wrangler login or exported CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID; cf auth login does not cover Wrangler), so hand it over:
| Task | Command |
| Tail production logs | pnpm exec wrangler tail <app>-production |
| Put a Preview secret | pnpm exec wrangler preview secret put … (rule ops/previews) |
hono request sees the bindings without a Wrangler config: in a cf project it defaults to --runtime vite, and the Cloudflare Vite plugin reads cloudflare.config.ts. --runtime workerd and the Node runtime's getPlatformProxy still need a Wrangler config.
Sandbox
cf devand--localcommands start workerd, so they needsandbox.network.allowLocalBindingand a sandbox-writableCLOUDFLARE_DEV_REGISTRY_PATH: cf passes the environment through unchanged, and Miniflare keeps its dev registry there. TheWRANGLER_*paths stay for the Workers Vitest pool and the Wrangler-only commands.hono requeststarts the Cloudflare Vite plugin without cf; its Miniflare reads the sameCLOUDFLARE_DEV_REGISTRY_PATH, and without a sandbox-writable one it fails withEPERMon its default registry directory and then hangs.- Telemetry: cf checks
DO_NOT_TRACK, thenCF_SEND_TELEMETRY, thenWRANGLER_SEND_METRICS. CI setsDO_NOT_TRACK=1andCF_SEND_TELEMETRY=false; agents run withCF_SEND_TELEMETRY=falsefrom the settingsenv. Humans turn it off once per machine withpnpm exec cf cli telemetry disable, which replaces thesend_metrics: falsethat left withwrangler.jsonc.pnpm exec cf cli telemetry statusnames the source.cf deployandcf workers versions createalso upload npm dependency metadata by default (cf1.0.0-beta.15);cd.ymlandpreview.ymlsetCLOUDFLARE_DEPENDENCIES_INSTRUMENTATION=false, so nothing leaves the pipeline.
Wrangler habits
| Habit | Now |
wrangler.jsonc, --env <name> | cloudflare.config.ts, --mode <name> |
wrangler dev / deploy / types | cf dev / cf deploy --prebuilt --mode production / cf workers types, through the app scripts |
Committed worker-configuration.d.ts, types:check | Gitignored .cloudflare/types/index.d.ts, regenerated before check-types; no check task |
dist/ | .cloudflare/output/v0/ |
wrangler check startup | cf workers check |
wrangler versions deploy, wrangler rollback | cf workers deployments create with the version id |
wrangler secret put (prompts for the value) | cf workers secrets update --type secret_text --text <value> (no prompt: read the value without echo, as in Secrets) |
| Waiting for "Ready on" | Vite's Local: banner |
Docs
The installed node_modules/cf/README.md and --help match the pinned beta; the pages below may lag it. Append index.md to a page URL for Markdown; where a page and the installed --help disagree, the help wins.
- Overview: https://developers.cloudflare.com/cf/
- From Wrangler: https://developers.cloudflare.com/cf/wrangler/migrate/ and the command mapping, https://developers.cloudflare.com/cf/wrangler/reference/
- Projects and
cloudflare.config.ts: https://developers.cloudflare.com/cf/projects/ and https://developers.cloudflare.com/cf/projects/cloudflare-config/ - CI and agents: https://developers.cloudflare.com/cf/ci/ and https://developers.cloudflare.com/cf/agents/
- Build Output: https://developers.cloudflare.com/workers/build-output/
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

