agentleFS
louisbrulenaudetlouisbrulenaudet/monorepo-template/.agents/skills/cf/SKILL.md

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

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
  1. Very specific:

    Run from the repo root; each script runs in its app directory, next to cloudflare.config.ts.

    line 20
  2. Very specific:

    Every --prebuilt command passes exactly the mode config.json records.

    line 43
  3. Very specific:

    Run cf dev, cf build, cf deploy, or cf init in a directory without cloudflare.config.ts (autoconfiguration rewrites the project), or cf …

    line 68
  4. Very specific:

    Every apps/front-app/.env* file holds public VITE_* values only, and the sandbox reads them through the /apps/front-app/.env* allow, …

    line 77

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. 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.
  2. pnpm exec cf schema <command words> - the API request a generated command sends (pnpm exec cf schema d1 raw).
  3. pnpm exec cf <command words> --help - flags at the installed version. --force is sometimes an API parameter rather than a confirmation skip: read the help before passing it.
  4. --dry-run where the help lists it - prints the request, or builds and checks without uploading.
  5. Run it.

Project commands

Run from the repo root; each script runs in its app directory, next to cloudflare.config.ts.

TaskCommandNotes
Dev serverpnpm --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
Buildpnpm turbo run build --filter=<app> (cf build)Production mode; writes .cloudflare/output/v0/
Env typespnpm types (cf workers types, worker-api)The turbo types task also runs before check-types; front-app has type generation off
Startup profilepnpm --filter=worker-api exec cf workers check --prebuilt --mode production, after a buildJSON bundle size and startup timings; writes worker-startup.cpuprofile (gitignored). Needs a Worker entrypoint, so not front-app
Deploy, uploadpnpm run deploy, pnpm run uploadHumans 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_id from the first entry of cf workers deployments list --worker <app>-production, never latest (CD uploads and Previews create newer versions that serve nothing). Then cf workers versions profile <version-id> --worker-id <app>-production --duration-ms 10000 --profile-type cpu > "$TMPDIR/<app>.pprof", or heap for 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: sentryMiddleware stays registered when SENTRY_DSN is empty.
  • Telemetry: the cloudflare-api MCP (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 dev runs mode development; cf build and cf deploy run production unless given --mode staging; the Workers Vitest pool loads test; a Preview build is ctx.isPreview under production. Any other mode throws in cloudflare.config.ts.
  • Select a mode with --mode, never Wrangler's --env.
  • Build Output, per app under .cloudflare/output/v0/: config.json (records buildContext.mode and isPreview), workers/default/worker.config.json, workers/default/bundle/ (the Worker plus its .map files, uploaded as source maps), workers/default/assets/ (the client build).
  • Every --prebuilt command passes exactly the mode config.json records; a mismatch fails ("The Build Output was created with mode …"). Preview output deploys only through cf previews deploy --prebuilt.
  • .cloudflare/** (Build Output, types/, local dev state/) is generated and gitignored, and the edit hook blocks hand edits. Change cloudflare.config.ts or the source, then rebuild or run pnpm 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

  • --local runs 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.
  • --local defaults to state/ under cf's global config directory, which is neither the app's dev state nor writable in the Claude Code sandbox. To use what cf dev wrote, 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 dev runs, the Local Explorer API answers on http://localhost:8700/cdn-cgi/local/explorer/api (:5174 for front-app); trace and log queries: skill run-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 when FORCE_COLOR is set, even on a pipe, which is why deploy-previews.sh runs cf previews deploy that way.
  • In a non-interactive session a destructive command without --force exits 1 instead of prompting.
  • cf workers versions create prints no JSON yet (upstream bug versions-upload-no-json-output): with WRANGLER_OUTPUT_FILE_PATH=<file> it appends an ND-JSON version-upload record (worker_name, version_id, preview_url) there, which CD reads. There is no --strict flag because cf always uploads strict: in CI a conflict (dashboard edits, remote-secret overrides) aborts with exit 1 and version_id: null, and the error's hint to remove --strict does not apply.
  • cf deploy --prebuilt --mode production --dry-run needs 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 (rules ops/cd, ops/previews, ops/release); hand the exact command to the user.
  • Log in: cf auth login (root script login:cloudflare) is the user's. cf reads CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID like Wrangler did; CF_ACCOUNT_ID is a deprecated alias.
  • Run cf dev, cf build, cf deploy, or cf init in a directory without cloudflare.config.ts (autoconfiguration rewrites the project), or cf migrate anywhere (it rewrites a Wrangler project's files for cf). A new app copies an existing app's cloudflare.config.ts and vite.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-run matched.

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 .env or the shell (SENTRY_DSN=… pnpm dev; turbo passes SENTRY_DSN to worker-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 sets SKIP_ENV_FILES=1 and sandboxed runs skip the .env (rule backend/workers-config).
  • Deployed secrets are declared with bindings.secret(); the test mode and Previews use bindings.text("") for SENTRY_DSN. Values go up with --secrets-file <path> on cf deploy / cf workers versions create (a JSON file outside the checkout, e.g. under $TMPDIR, deleted after use: a dotenv file expands $VAR and yields to a same-named process environment variable, even an empty one), or one at a time with read -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 public VITE_* values only, and the sandbox reads them through the **/apps/front-app/.env* allow, because build hashes 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:

TaskCommand
Tail production logspnpm exec wrangler tail <app>-production
Put a Preview secretpnpm 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 dev and --local commands start workerd, so they need sandbox.network.allowLocalBinding and a sandbox-writable CLOUDFLARE_DEV_REGISTRY_PATH: cf passes the environment through unchanged, and Miniflare keeps its dev registry there. The WRANGLER_* paths stay for the Workers Vitest pool and the Wrangler-only commands.
  • hono request starts the Cloudflare Vite plugin without cf; its Miniflare reads the same CLOUDFLARE_DEV_REGISTRY_PATH, and without a sandbox-writable one it fails with EPERM on its default registry directory and then hangs.
  • Telemetry: cf checks DO_NOT_TRACK, then CF_SEND_TELEMETRY, then WRANGLER_SEND_METRICS. CI sets DO_NOT_TRACK=1 and CF_SEND_TELEMETRY=false; agents run with CF_SEND_TELEMETRY=false from the settings env. Humans turn it off once per machine with pnpm exec cf cli telemetry disable, which replaces the send_metrics: false that left with wrangler.jsonc. pnpm exec cf cli telemetry status names the source. cf deploy and cf workers versions create also upload npm dependency metadata by default (cf 1.0.0-beta.15); cd.yml and preview.yml set CLOUDFLARE_DEPENDENCIES_INSTRUMENTATION=false, so nothing leaves the pipeline.

Wrangler habits

HabitNow
wrangler.jsonc, --env <name>cloudflare.config.ts, --mode <name>
wrangler dev / deploy / typescf dev / cf deploy --prebuilt --mode production / cf workers types, through the app scripts
Committed worker-configuration.d.ts, types:checkGitignored .cloudflare/types/index.d.ts, regenerated before check-types; no check task
dist/.cloudflare/output/v0/
wrangler check startupcf workers check
wrangler versions deploy, wrangler rollbackcf 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.