Cloudflare Cf CLI

Cloudflare cf CLI

cf is Cloudflare's new unified CLI, announced April 2026, intended to eventually become the next major version of Wrangler. It exposes ~3,000 API operations across 100+ products through one consistent command surface. This skill is about using it correctly while it is still a technical preview.

When to invoke

• The user mentions cf, npx cf, or "the new Cloudflare CLI" / "CLI for all of Cloudflare".
• A script or workflow is about to replace wrangler ... with cf ....
• An agent is generating cf commands and may not know the flag conventions.
• A cf invocation behaved as if it targeted production when the user expected local.
• The user is choosing between cf, wrangler, direct REST, the official cloudflare SDK, or Terraform.

Cross-cutting rules

1. cf is technical preview. Only a small subset of products is wired up. Conventions can shift between releases. wrangler stays authoritative for CI/CD until cf reaches GA. Use cf for local exploration, ad-hoc agent work, and feedback. If cf must be used in a script, pin the exact version — never unpinned npx cf in CI.
2. cf defaults to the REMOTE resource. Without --local, every mutation hits production. See the local-vs-remote trap.
3. Token scoping rules are identical to the cloudflare-dns-zones skill — never the Global API Key, scope to minimum permissions on specific zones/accounts. For cf additionally: prefer a separate non-prod token for local work, so an accidental remote write fails 403 instead of corrupting production.
4. Don't guess flag names by analogy. cf enforces consistent flags across the surface (--force, --json, --local). Verify with cf <command> --help rather than reaching for the synonym another CLI uses.

Verify current preview status before recommending: https://blog.cloudflare.com/cf-cli-local-explorer/. Training data ages fast on preview tools.

Don't confuse cf with neighbors

If the user says "I installed cf and it does X" but X matches cfcli's shape (~/.cfcli.yml, CF_API_KEY env), they probably installed the wrong package. Have them check which cf and the npm package name.

Install and auth

npx cf <command>                    # one-off
npm install -g cf                   # global
npm install -g cf@<version>         # pinned — use this in scripts
cf --version                        # verify binary

Auth: cf is built on the same API as Wrangler and the official SDK. Treat CLOUDFLARE_API_TOKEN as canonical until cf --help on your installed version documents otherwise.

Flag conventions

--json is intended to be supported on every command but the preview may not cover all of them yet. If a command lacks --json, fall back to REST + jq for that one operation rather than parsing human output.

The local-vs-remote trap

cf mutations target production unless --local is passed. Example:

# Developer running `wrangler dev` in another terminal, expects this to seed local KV:
cf kv put session:abc '{"user":"test"}'      # ❌ writes to PRODUCTION

# Correct — seeds the simulated namespace Local Explorer / wrangler dev see:
cf kv put session:abc '{"user":"test"}' --local

Guardrails:

1. Non-prod token for local work (see cross-cutting rule 3). A 403 on accidental remote writes beats silent corruption.
2. Prefer Local Explorer for local seeding. Press e in the wrangler dev terminal, or point the agent at /cdn-cgi/explorer/api (OpenAPI spec advertised at that URL). Local Explorer is local-only by construction — no --local to forget.
3. In review: any cf mutation (put, delete, create, update) without --local is production-targeting. Confirm intent.

There is no global config knob in the preview to flip the default. --local is per-invocation.

Coexistence with Wrangler

cf shares wrangler.jsonc — the same config describes bindings, routes, and compatibility flags for both tools.

In practice during preview:

• A repo can use wrangler for deploy/dev and cf for ad-hoc reads of resources Wrangler has no command for (because cf covers more API surface).
• cf reading a KV namespace defined as a Wrangler binding works because both tools resolve wrangler.jsonc the same way.
• Don't mix them inside one CI job. Pick one per workflow step; mixing makes failures harder to debug when convention drift hits.

Agent-mode usage

cf is designed to be agent-usable. Two patterns:

1. Invoke cf directly. --json is the machine contract. Don't scrape human output.
2. Point the agent at the Local Explorer OpenAPI. When wrangler dev is running, <dev-host>:<port>/cdn-cgi/explorer/api advertises an OpenAPI spec covering the simulated KV / R2 / D1 / Durable Objects / Workflows. An agent that reads OpenAPI can manage local resources without cf installed at all — useful for sandboxed agents.

When to use what

Don't reach for cf in CI just because it's new. Reach for it when it shortens a script you'd otherwise write with curl + jq — and pin the version when you do.

Anti-patterns

• ❌ Unpinned npx cf in CI. Pin the version or use wrangler.
• ❌ Treating cf and cfcli as the same tool. Different package, different conventions (~/.cfcli.yml, CF_API_KEY), different auth model.
• ❌ cf mutation (put, delete, create, update) without --local in a dev context. Default is remote.
• ❌ Parsing cf human output. Use --json or fall back to REST.
• ❌ Mixing cf and wrangler in the same CI job during preview.
• ❌ Using flag analogues from other CLIs (--yes, --format=json, --preview). The documented conventions are --force, --json, --local — verify with cf <cmd> --help.
• ❌ Recommending cf for DNS record CRUD when REST + the cloudflare-dns-zones skill is the proven path.

Cross-skill notes

• For DNS-specific work via REST, see the cloudflare-dns-zones skill — GA, unaffected by cf's preview status.
• For R2 endpoint detection and credentials versus generic S3, see the cloud-storage-identification skill.
• For Terraform-managed Cloudflare resources, the terraform-workflows skill covers plan review and provider-upgrade discipline.
• A cloudflare-local-explorer companion skill is planned; until then, agent-mode usage is the brief.