🎉Black Friday deal: 40% off all lifetime licenses with code BF2026

Cloudflare R2 S3 Endpoint Setup (2026): CLI, SDK & Mac GUI

Short answer: Cloudflare R2's S3 API endpoint is https://<account-id>.r2.cloudflarestorage.com. Use an R2 API token's Access Key ID and Secret Access Key as credentials, and set the region to auto. Any S3 client that supports a custom endpoint works with those three values.

This guide shows where to find each value, then gives copy-ready setup for the AWS CLI, Python boto3, the JavaScript SDK v3, s5cmd, rclone, Cyberduck, and a Mac S3 GUI.

Prefer a GUI? Download BucketMate or open the Web app. Same R2 connection on iPhone. Full GUI walkthrough: Cloudflare R2 GUI for macOS. Client comparison: best S3 GUI for macOS.

1) Grab your R2 connection credentials

You need 3 things:

  • Endpoint URL (e.g. https://<account-id>.r2.cloudflarestorage.com)
  • Access Key ID
  • Secret Access Key

Where to find them:

  1. In the Cloudflare dashboard, go to R2.
  2. On the overview, copy your Account ID. Then the S3 API endpoint URL is https://<account-id>.r2.cloudflarestorage.com.
  3. Click Manage R2 API Tokens → Create API Token and copy the Access Key ID and Secret (you’ll only see the secret once).

Heads-up: R2 supports virtual-hosted style (my-bucket.<account-id>.r2.cloudflarestorage.com) and path-style (<account-id>.r2.cloudflarestorage.com/my-bucket). Use either; if a client misbehaves, force path-style in its settings.

2) Connect R2 in BucketMate (Mac GUI)

BucketMate is a native S3 GUI for macOS, iOS, and Web. Use the same endpoint and keys you just copied - on Mac, in the iOS app on iPhone, or in the browser.

  1. Open BucketMate → Add connection → Cloudflare R2.
  2. Input your Endpoint URL, Access Key ID, and Secret. Region is auto.
  3. Click Test Connection to verify your credentials.
  4. Once verified, click Connect to browse your buckets instantly.

Need more context on GUI vs dashboard vs CLI? Read Cloudflare R2 GUI for macOS. Compare clients in best S3 GUI for macOS.

Keep the CLI and SDK snippets below for scripts, CI, and bulk transfers.

3) AWS CLI: quick setup

Use a fresh terminal session:

export AWS_ACCESS_KEY_ID="<your-access-key-id>"
export AWS_SECRET_ACCESS_KEY="<your-secret-access-key>"
export AWS_REGION="auto"
# Newer AWS CLI also supports service-specific env vars:
export AWS_ENDPOINT_URL_S3="https://<account-id>.r2.cloudflarestorage.com"

List buckets and copy an object:

aws s3 ls --endpoint-url "https://<account-id>.r2.cloudflarestorage.com"

aws s3 cp ./logo.png s3://my-r2-bucket/assets/logo.png \
  --endpoint-url "https://<account-id>.r2.cloudflarestorage.com"

Prefer profiles? You can keep using --endpoint-url ... with --profile r2, or set AWS_ENDPOINT_URL_S3 in your shell profile so the CLI picks it up automatically.

4) JavaScript (AWS SDK v3)

Minimal upload using @aws-sdk/client-s3:

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  region: "auto",
  endpoint: "https://<account-id>.r2.cloudflarestorage.com",
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
  // If a client or library assumes AWS-only virtual hosting, un-comment:
  // forcePathStyle: true,
});

await s3.send(new PutObjectCommand({
  Bucket: "my-r2-bucket",
  Key: "welcome.txt",
  Body: "Hello from Cloudflare R2!",
  ContentType: "text/plain",
}));

Key settings:

  • region: "auto" is required for R2.
  • Use the account-scoped endpoint shown above.
  • Toggle forcePathStyle only if your stack insists on virtual-hosted bucket subdomains.

5) Python (boto3)

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://<account-id>.r2.cloudflarestorage.com",
    aws_access_key_id="<your-access-key-id>",
    aws_secret_access_key="<your-secret-access-key>",
    region_name="auto",
)

s3.upload_file("./logo.png", "my-r2-bucket", "assets/logo.png")

for obj in s3.list_objects_v2(Bucket="my-r2-bucket").get("Contents", []):
    print(obj["Key"], obj["Size"])

endpoint_url and region_name="auto" are the only R2-specific settings. Everything else is standard boto3.

6) s5cmd & rclone (fast transfers)

s5cmd

# Install: macOS → brew install peak/tap/s5cmd
AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... AWS_REGION=auto \
s5cmd --endpoint-url https://<account-id>.r2.cloudflarestorage.com \
  cp ./big.iso s3://my-r2-bucket/

rclone (preset provider)

# Guided setup
rclone config
# Choose: "Amazon S3 Compliant Storage Providers" → "Cloudflare R2 storage"
# Enter access key, secret, region=auto, endpoint=https://<account-id>.r2.cloudflarestorage.com

# Then:
rclone ls r2:my-r2-bucket
rclone copy ./folder r2:my-r2-bucket/folder

7) Cyberduck

  1. Open Cyberduck → Open Connection.
  2. Choose Amazon S3 as the connection type.
  3. Set Server to <account-id>.r2.cloudflarestorage.com and Port to 443.
  4. Enter the Access Key ID and Secret Access Key from your R2 API token.
  5. Connect. If listing fails, the token may be scoped to specific buckets - add the bucket name to the path.

For a side-by-side of Cyberduck and a native Mac client, see BucketMate vs Cyberduck.

Troubleshooting

  • AccessDenied: Re-create the API token with Edit or appropriate permissions for your buckets.
  • 403/HeadBucket issues: Set path-style addressing in your client (e.g., forcePathStyle: true in SDKs).
  • NoSuchBucket: Bucket name must follow S3 rules (lowercase, numbers, hyphens); verify the spelling.
  • Signature mismatch: Ensure your machine clock is correct; SigV4 is time-sensitive.
  • HTTP rejected: Use https:// for all endpoints.