Cloudflare cf CLI: How Coding Agents Discover & Run Commands

This article explains how coding agents discover and safely run commands using Cloudflare’s cf CLI, covering the discovery mechanisms, safety practices, and common pitfalls. You’ll learn the exact steps agents use to explore the CLI, execute commands, and avoid destructive actions.

Background: What Is the cf CLI and Why Do Agents Use It?

Cloudflare’s cf CLI (also known as cloudflare) is a command-line tool for managing Cloudflare resources—zones, DNS records, Workers, Pages, R2 buckets, and more. Coding agents (AI assistants like GitHub Copilot, Cursor, or custom automation) often need to interact with Cloudflare to deploy or debug. Unlike a human who reads documentation, an agent must programmatically discover the CLI’s structure and then execute commands without causing accidental damage.

How Agents Discover Available Commands

Agents typically start by running cf --help to get a top-level list of commands and groups. This output shows categories like dns, workers, pages, and r2. Then they drill down with cf dns --help or cf workers deploy --help to see subcommands and flags.

Command tree traversal: The agent recursively runs --help on each subcommand to build a mental map of the CLI.
Shell completion: Some agents parse the output of cf completion to get a machine-readable list of all commands.
Man pages or online docs: If the CLI has a man page, the agent may fetch that, but the built-in help is usually sufficient.

Discovering Flags and Arguments

Beyond command names, agents need to know what flags each command accepts. The --help output lists flags with descriptions and whether they are required. For example, cf dns create --help shows flags like --zone, --name, --content, and --type. Agents also look at examples in the help text—many Cloudflare CLI commands include usage examples that illustrate typical invocations.

For complex commands, agents may run cf --help multiple times with different subcommands to understand the full syntax. They also check the CLI version with cf --version to ensure they use features available in that version.

Safe Execution: Dry Runs and Confirmation

The most critical safety feature is the --dry-run flag, available on many mutating commands (like cf dns create or cf workers deploy). This flag shows what would happen without actually making changes. Agents should always run a dry run first, inspect the output, and only then execute the real command.

Run cf dns create --dry-run --zone example.com --name test --content 192.0.2.1 --type A to preview.
Review the output for correctness (zone, name, content, type).
If correct, run the same command without --dry-run.

Some commands (like cf pages deploy) may prompt for confirmation in interactive mode. Agents should use --yes or --force only when they are certain, but better practice is to avoid forcing and instead rely on dry runs.

Authentication and Credential Handling

Agents must authenticate with Cloudflare. The cf CLI uses API tokens or global API keys, stored in environment variables like CLOUDFLARE_API_TOKEN or in a config file (~/.cloudflare/config). Coding agents should never hardcode credentials in scripts or commit them to repositories. Instead, they should read from environment variables or use a secrets manager.

When an agent runs a command that requires authentication, it will fail with a clear error if credentials are missing. The agent can then prompt the user to set the environment variable or run cf login (which opens a browser for OAuth). For automation, API tokens are preferred because they can be scoped to specific permissions (e.g., only DNS edit) and revoked easily.

Common Pitfalls and How to Avoid Them

One common mistake is using the wrong zone ID instead of the zone name. The CLI often accepts either, but if both are provided, they must match. Another pitfall is forgetting to specify the --type flag when creating a DNS record, which defaults to something unexpected. Agents should always validate the output of cf dns list after a change.

Another issue is that some commands are destructive (like cf dns delete or cf workers delete). Agents must double-check the resource name and ID before executing. Using --dry-run is especially important here, but not all delete commands support it—so agents should list resources first and confirm the exact identifier.

Comparing cf CLI with Other Tools

Cloudflare also offers a REST API and Terraform provider. The CLI is more convenient for quick tasks and scripting, while Terraform is better for infrastructure-as-code. Agents might choose the CLI for one-off operations and Terraform for reproducible deployments. The CLI is also faster for simple lookups like cf dns list.

Costs and Rate Limits

Using the CLI itself is free, but it consumes API requests, which are subject to rate limits. Cloudflare’s API has a limit of 1,200 requests per five minutes for free accounts, and higher for paid plans. Agents should be mindful of loops that make many calls; adding a small delay between commands can avoid hitting the limit. If a 429 error occurs, the agent should back off and retry after the reset period.

Frequently Asked Questions

How do I see all available commands in cf CLI?

Run cf --help to get the top-level list. For subcommands, run cf --help (e.g., cf dns --help). You can also use cf completion to generate a shell completion script that lists every command.

What does the –dry-run flag do?

It simulates the command without making actual changes. It prints what would be done, such as the DNS record that would be created or the Worker that would be deployed. This is safe to run and highly recommended before any mutating action.

Can I use cf CLI without a browser for authentication?

Yes, you can set the environment variable CLOUDFLARE_API_TOKEN with an API token created in the Cloudflare dashboard. This works headless and is preferred for automation. Alternatively, you can use cf login --token to store the token in the config file.

Why does my command fail with “Invalid zone”?

This usually means the zone name or ID is incorrect. Check that the zone exists in your account and that you have permission to access it. Use cf zone list to see your zones and copy the exact name or ID.

Is it safe to run cf commands in a CI/CD pipeline?

Yes, if you use scoped API tokens with minimal permissions, run dry runs in a staging environment, and avoid using global API keys. Also, ensure the token is stored as a secret in your CI system, not in the repository.

How do I undo a mistake made with cf CLI?

It depends on the resource. For DNS records, you can delete the incorrect record and create a new one. For Workers, you can redeploy a previous version. The CLI does not have a built-in undo, so always double-check before executing and consider using version control for configuration files.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →