Skip to main content

Bucket Management via CLI

Buckets are the foundational top-level containers in R2. While the Cloudflare Dashboard provides a GUI, managing buckets via the CLI (wrangler and aws s3api) ensures infrastructure predictability and scriptability.

Creating Buckets & Location Hints​

By default, Cloudflare dynamically decides the optimal physical location for a new bucket based on the location of the request that creates it. However, for latency-sensitive applications, you must use location hints.

Using Location Hints (Wrangler)​

wrangler r2 bucket create production-assets --location weur

Valid location hints include:

  • wnam: Western North America
  • enam: Eastern North America
  • weur: Western Europe
  • eeur: Eastern Europe
  • apac: Asia-Pacific
  • oc: Oceania

[!TIP] Why Location Hints Matter: While R2 edge caching reduces delivery latency globally, cache misses and write operations must travel to the bucket's physical location. Placing the bucket in weur when your primary ingestion servers are in Germany drastically improves upload speeds.

Creating via AWS CLI​

To create a bucket without location hints using standard S3 commands:

r2-aws mb s3://analytics-data-lake

Deep Bucket Configuration (S3 API)​

The high-level aws s3 commands (cp, sync, mb) are wrappers. For fine-grained bucket control, we use the aws s3api command, which interacts directly with the underlying REST endpoints.

Listing Buckets with Metadata​

To see all buckets along with their creation dates in JSON format:

r2-awsapi list-buckets | jq '.Buckets[] | {Name, CreationDate}'

Applying Object Lifecycle Policies​

Lifecycle policies allow you to automatically delete objects after a certain period, saving storage costs for temporary data like logs or ephemeral backups.

  1. Create a lifecycle.json file to delete objects older than 30 days:
lifecycle.json
{
  "Rules": [
    {
      "ID": "DeleteOldLogs",
      "Prefix": "logs/",
      "Status": "Enabled",
      "Expiration": {
        "Days": 30
      }
    }
  ]
}
  1. Apply the policy to the bucket:
r2-awsapi put-bucket-lifecycle-configuration \
  --bucket analytics-data-lake \
  --lifecycle-configuration file://lifecycle.json
  1. Verify the policy:
r2-awsapi get-bucket-lifecycle-configuration --bucket analytics-data-lake

Bucket Versioning​

[!WARNING] While you can send the put-bucket-versioning command to R2, Cloudflare is still rolling out full native support for Object Versioning. Relying on this for critical undo/recovery operations is not recommended until general availability is officially announced.

Safely Deleting Buckets​

Buckets must be completely empty (including hidden multipart fragments) before they can be deleted. Attempting to delete a non-empty bucket will result in a BucketNotEmpty error.

Standard Delete (Safe):

wrangler r2 bucket delete <BUCKET_NAME>
# OR
r2-aws rb s3://<BUCKET_NAME>

Forceful Delete (Danger!): To systematically delete all objects, metadata, and then the bucket itself:

r2-aws rb s3://<BUCKET_NAME> --force

Infrastructure as Code (Terraform)​

For enterprise environments, creating buckets via CLI scripts is discouraged in favor of Infrastructure as Code (IaC). R2 is fully supported by the Cloudflare Terraform provider.

terraform {
  required_providers {
    cloudflare = {
      source = "cloudflare/cloudflare"
      version = "~> 4.0"
    }
  }
}

resource "cloudflare_r2_bucket" "example" {
  account_id = var.cloudflare_account_id
  name       = "terraform-managed-bucket"
  location   = "weur"
}