Convention: What are the critical CLI conventions when using wrangler wi...

Documentation for Sessions

📏 Convention: What are the critical CLI conventions when using wrangler wi...

Date: 2026-02-12
Time: 04:22:29 UTC
Session: gspace1-108.14
Agent: storage
Confidence: 99%
Status: ✅ Documented

📋 Decision Context

Question:

What are the critical CLI conventions when using wrangler with Cloudflare R2?

Task: GoGrab Pulse - Wrangler R2 CLI conventions

🎯 Decision Made

Chosen:

Always use --remote flag for R2 operations; always set --content-type for uploads

Options Considered:

  1. Use wrangler defaults
  2. Always specify --remote flag and content-type

💭 Reasoning

Critical wrangler R2 CLI rules that caused bugs when not followed: (1) ALWAYS use --remote with wrangler r2 object put and wrangler r2 object get. Without --remote, wrangler defaults to local Miniflare storage, and files appear to upload successfully but never reach the cloud bucket. This is the #1 gotcha. (2) ALWAYS set --content-type when uploading: audio/mpeg for MP3s, image/jpeg for JPGs, image/png for PNGs. Without it, R2 may serve files with incorrect content-type headers. (3) R2 bucket name: gograb-pulse-music. (4) Key structure: songs/{filename}.mp3 for audio, covers/{filename}.jpg for art. (5) List bucket contents: npx wrangler r2 object list gograb-pulse-music --remote. (6) Delete: npx wrangler r2 object delete gograb-pulse-music/songs/{file} --remote. (7) The Cloudflare API token must have R2 read/write permissions (Object Read & Write). (8) Public access is via r2.dev managed domain (enabled in Cloudflare dashboard or API), not a custom domain. The public URL format is: https://pub-{hash}.r2.dev/songs/{filename}.mp3. (9) The sync script (tools/scripts/sync-pulse-music.sh) automates bulk uploads with proper flags.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation