NAME

cloudflare-api - call Cloudflare::API resource methods from the command line

SYNOPSIS

cloudflare-api --resource r2 --action list_buckets --paginate --max-pages 2
cloudflare-api --resource kv --action create_namespace --arg-json '{"title":"demo"}'
cloudflare-api --resource workers --action upload_assets --arg my-app --arg dist --param prefix=/docs
cloudflare-api --method GET --path /accounts --full-response

DESCRIPTION

cloudflare-api calls a supported Cloudflare::API resource method or makes a low-level JSON request. It reads CLOUDFLARE_API_TOKEN and, for account-scoped methods, CLOUDFLARE_ACCOUNT_ID from the environment. It prints the decoded Cloudflare result as pretty JSON by default; --full-response retains the entire Cloudflare envelope. The script does not build Worker code or transfer R2 objects.

Choose one mode: --resource NAME --action NAME for a named method, or --method VERB --path /relative/path for a low-level request. Positional arguments supplied with --arg* are passed in their command-line order. Named arguments supplied with --param* become method options, or query parameters in low-level mode. Other positional command-line arguments are rejected.

OPTIONS

Selection and authentication

• --resource NAME, --action NAME

  Call a named method on accounts, zones, workers, r2, kv, d1, queues, hyperdrive, or secrets_store. Both options are required together. Only methods in the script's allowlist can be called; consult the resource module sidecars for arguments and results. The script does not expose every module method, including workers()->download_script(), whose body is not JSON.

• --method VERB, --path /relative/path

  Call a low-level JSON endpoint through Cloudflare::API->request(). Both options are required and cannot be combined with --resource or --action. The method is uppercased. The path must begin with exactly one slash and cannot be an absolute URL. At most one positional argument is accepted as a JSON request body; named parameters become query parameters. Dynamic path segments must be percent-encoded by the caller.

• --account-id ID

  Override CLOUDFLARE_ACCOUNT_ID and Wrangler account discovery for this invocation. Account-scoped methods require an ID; account and zone lookups do not.

• --auth=wrangler

  Run wrangler auth token --json and use its API token or refreshed OAuth token instead of the environment token. For an account-scoped named method, also run wrangler whoami --json and use the account ID when exactly one account is available. Select among multiple accounts with --account-id or CLOUDFLARE_ACCOUNT_ID; these explicit values take precedence and skip account discovery. Wrangler must be installed and logged in. Run wrangler login separately if necessary. Wrangler itself prioritizes an existing CLOUDFLARE_API_TOKEN over its OAuth login. API key and email credentials are not supported. No token option is accepted on the command line.

Positional and named arguments

• --arg VALUE

  Append a literal string positional argument. Repeat to supply several arguments in order.

• --arg-bool true|false, --arg-array JSON, --arg-hash JSON, --arg-json JSON, --arg-json-file FILE

  Append a typed positional argument. Boolean values are case-insensitive; array and hash forms require the matching JSON container. The JSON forms accept any JSON value, directly or read from a file. To pass a private JSON body without putting it in the process arguments, pipe it to --arg-json-file /dev/stdin.

• --arg-dumper-file FILE

  Evaluate a trusted Data::Dumper file as Perl and append its result. The file can execute arbitrary Perl code; use JSON for data from other sources.

• --param NAME=VALUE

  Pass one literal string named argument. The first = separates the name from the value, so a value may contain further equals signs. Names must begin with a letter or underscore and contain only letters, digits, or underscores. A repeated name replaces its earlier value.

• --param-bool NAME=true|false, --param-json NAME=JSON, --param-json-file NAME=FILE

  Pass a typed named argument. JSON file content is decoded before the method call. For list actions these usually become Cloudflare query filters; for other actions they can be method options such as metadata and files for a Worker upload.

• --param-dumper-file NAME=FILE

  Evaluate a trusted Data::Dumper file as Perl and pass its result under NAME. This can execute arbitrary Perl code; prefer JSON for untrusted input.

Worker static assets

• --asset FILE

  Append a local file to the asset source list. Repeat as needed. A bare filename uses its basename as its URL path.

• --asset-list-json FILE

  Append entries from a JSON array of filenames or objects with path, optional URL name, and optional content_type. Repeat for multiple files.

• --asset-list-text FILE, --asset-list-stdin

  Append one filename per line from a text file or standard input. Empty lines are ignored; spaces in filenames are preserved. The stdin option may appear only once. Sources combine in option order.

  All four asset-list options require --resource workers --action upload_assets and exactly one string --arg naming the Worker. They create the method's second positional argument as a file array; do not also pass a directory, array, or path-map source argument. The array cannot be empty. Alternatively, pass a directory with a second --arg, or an asset array with --arg-json-file. --param prefix=/docs sets a URL prefix. The command prints the manifest and short-lived completion JWT returned by upload_assets(); asset upload alone does not deploy a Worker. Treat the JWT as a credential.

Output and pagination

• --output json|dumper

  Print pretty, canonical JSON (the default) or Perl Data::Dumper output to standard output.

• --full-response, --no-full-response

  Select the complete decoded Cloudflare envelope or its result. The default is the unwrapped result. With pagination, the selection applies to each page; the output is still an array. upload_assets() returns its own manifest and JWT structure rather than a Cloudflare envelope.

• --paginate, --no-paginate

  Follow cursor-based or numbered pages for named actions starting with list. The output is an array of page results, preserving page boundaries. Without a limit, every page reported by Cloudflare is fetched. Pagination is unavailable for raw requests and non-list actions.

• --max-pages N, --per-page N

  Limit pagination to a positive number of pages, or send positive per_page=N as a named list filter. --max-pages requires --paginate. Pagination stops when Cloudflare supplies no next page; a repeated cursor causes an error.

Help and diagnostics

• --help, -h, -?

  Print brief help and exit.

• --man

  Print the script's embedded manual and exit.

• --version

  Print the script name and Cloudflare::API version and exit.

• --dump-opt, --dump_opt, --opt

  Print parsed options, arguments, and parameters as Data::Dumper without creating a client or requiring a token. This output can disclose values. The script rejects this mode for selected Secrets Store, Worker secret, and Hyperdrive write actions, but other actions may also carry private data; do not use it with secrets.

ENVIRONMENT

• CLOUDFLARE_API_TOKEN — Bearer token used unless --auth=wrangler is supplied. Obtain a token with only the permissions needed for the requested action.

• CLOUDFLARE_ACCOUNT_ID — Default account ID for account-scoped resource methods; overridden by --account-id and used in preference to Wrangler account discovery.

EXAMPLES

cloudflare-api --resource zones --action list --param status=active
cloudflare-api --resource kv --action list_namespaces \
    --paginate --per-page 20 --max-pages 2 --full-response
cloudflare-api --resource workers --action upload_assets \
    --arg my-app --asset dist/index.html --asset-list-text images.txt \
    --param prefix=/docs
cloudflare-api --resource secrets_store --action create_secret \
    --arg my-store --arg-json-file /dev/stdin < secrets.json
For a Worker version upload, pass the Worker name through C<--arg> and prepared C<metadata> and C<files> through C<--param-json-file NAME=FILE>. Version upload does not activate a deployment; consult C<Cloudflare::API::Workers> for the staging and deployment sequence. A secret body supplied through standard input still appears in the command's output if Cloudflare returns it; handle the output accordingly.

RETURN VALUES AND ERRORS

Successful requests print the result followed by a newline and exit with status zero. JSON output preserves Cloudflare's response shape; a paginated list prints an array of pages. Input validation, missing credentials or account context, HTTP and transport errors, and Cloudflare responses reporting failure terminate with a non-zero status and a diagnostic on standard error. No write is automatically rolled back.

SEE ALSO

Cloudflare::API, Cloudflare::API::Workers, the other resource module sidecars, and cloudflare-api --man.

AUTHOR

Andrew Speer mailto:andrew.speer@isolutions.com.au

LICENSE and COPYRIGHT

Copyright (c) 2026 Andrew Speer. This software is free software under the same terms as Perl 5.