Skip to main content

CLI and Tooling Setup

To interact with R2 effectively, we need robust CLI tooling. While Cloudflare provides wrangler for seamless integration within their ecosystem, the standard aws CLI remains the industry standard for bulk operations, CI/CD, and heavy lifting.

We will configure both to ensure you have a complete "gold standard" toolchain.

Tool 1: Cloudflare Wrangler​

Wrangler is the official CLI for Cloudflare Developer Platform. It uses your Cloudflare dashboard session, meaning no manual token management is required for basic local development.

Installation​

npm install -g wrangler

Authentication​

Run the login command and authenticate via your browser:

wrangler login

Verify your authentication and view your account ID:

wrangler whoami

[!IMPORTANT] CI/CD Integration: When running Wrangler in headless environments (GitHub Actions, GitLab CI), you cannot use wrangler login. Instead, generate an API Token from the Cloudflare Dashboard (with R2 Edit permissions) and set it as an environment variable: CLOUDFLARE_API_TOKEN. Wrangler will automatically use it.

Tool 2: The AWS CLI v2​

Because R2 is S3-compatible, the aws CLI is the most powerful tool for interacting with it.

Installation​

Install AWS CLI v2 according to your OS (Ubuntu/Debian example):

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

Retrieving R2 Credentials​

Unlike Wrangler, the AWS CLI requires dedicated R2 S3 API tokens.

  1. Navigate to the Cloudflare Dashboard -> R2 -> Manage R2 API Tokens.
  2. Click Create API token.
  3. Grant Admin Read & Write permissions (for full CLI control).
  4. Save the Access Key ID and Secret Access Key.
  5. Note your S3 API Endpoint: https://<YOUR_ACCOUNT_ID>.r2.cloudflarestorage.com.

Multi-Environment Profile Setup​

Do not overwrite your default AWS credentials if you use AWS. Instead, create a dedicated profile for R2. This is a critical best practice for preventing accidental data overwrites across cloud providers.

Configure the profile (we will name it r2):

aws configure --profile r2

When prompted:

  • AWS Access Key ID: Paste your R2 Access Key ID.
  • AWS Secret Access Key: Paste your R2 Secret Access Key.
  • Default region name: Enter auto. (Required for R2)
  • Default output format: Enter json.

Creating a Robust Alias​

Typing --profile r2 --endpoint-url https://... for every command is tedious and prone to error. Create a permanent shell alias to streamline this.

Open your ~/.bashrc or ~/.zshrc and add:

# Cloudflare R2 AWS CLI Alias
export R2_ACCOUNT_ID="your-cloudflare-account-id-here"
alias r2-aws='aws s3 --profile r2 --endpoint-url https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com'
alias r2-awsapi='aws s3api --profile r2 --endpoint-url https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com'

Apply the changes:

source ~/.bashrc

Verifying the Toolchain​

Let's ensure both tools are communicating with Cloudflare successfully.

Test Wrangler:

wrangler r2 bucket list

Test AWS CLI:

r2-aws ls

Both should return an empty list (or your existing buckets) without any authentication errors.

Troubleshooting Configuration​

SignatureDoesNotMatch Error​

If the AWS CLI returns a signature error, your Secret Key is likely incorrect, or your client is trying to use an incompatible AWS Signature version. Fix: Ensure your ~/.aws/config file for the r2 profile specifies the correct region and signature version:

[profile r2]
region = auto
s3 =
    signature_version = s3v4

Enabling Verbose Debugging​

If commands hang or fail cryptically, use the --debug flag to trace the raw HTTP payload:

r2-awsapi list-buckets --debug

Look at the HTTP request headers to confirm the correct endpoint and authorization scheme are being used.