r2put

CLI tool for uploading files to Cloudflare R2 with animated terminal UI, progress bars, and presigned download URLs.

Quick Start

# Install
npm install r2put

# Set credentials
export CLOUDFLARE_ACCOUNT_ID="your-account-id"
export R2_ACCESS_KEY_ID="your-access-key-id"
export R2_SECRET_ACCESS_KEY="your-secret-access-key"

# Upload file
r2put --file ./data.bin --bucket production-v4

See Quick Start Guide for detailed setup instructions.

Key Information for Agents

Execution Model:

• CLI-only tool: No programmatic API; must be invoked via command line
• Synchronous execution: Blocks until upload completes or fails
• Single file upload: One file per invocation
• Exit codes: 0 on success, 1 on error

Required Environment Variables:

• CLOUDFLARE_ACCOUNT_ID: Cloudflare Account ID
• R2_ACCESS_KEY_ID: R2 API Access Key ID
• R2_SECRET_ACCESS_KEY: R2 API Secret Access Key

Default Behaviors:

• Object key: Uses filename from --file if --key not specified
• Region hint: WNAM (display only, doesn't affect upload)
• MIME type: application/octet-stream for unknown extensions
• Presigned URL expiration: 3600 seconds (1 hour)
• Metadata: Automatically adds uploaded-at (ISO 8601) and original-filename

Lifecycle:

1. Validates file existence and environment variables
2. Connects to Cloudflare R2
3. Uploads file with metadata
4. Generates presigned URL on success
5. Displays result in terminal UI
6. Exits with appropriate code

CLI Interface

r2put --file <path> --bucket <name> [--key <key>] [--region <region>] [--help]

Options:

• --file, -f <path> - Path to file to upload (required)
• --bucket, -b <name> - Target R2 bucket name (required)
• --key, -k <key> - Custom object key (optional, defaults to filename)
• --region, -r <region> - Region hint for display (optional, default: "WNAM")
• --help, -h - Show help message

See CLI Interface Reference for complete documentation.

Quick Reference

Installation

npm install r2put          # Global
npm install r2put --save-dev  # Local
npx r2put                  # Without installation

Basic Usage

# Upload with default key
r2put --file ./data.bin --bucket production-v4

# Upload with custom key
r2put -f ./image.png -b assets -k images/hero.png

# Specify region hint
r2put --file ./backup.tar.gz --bucket backups --region ENAM

Exit Codes

• 0 - Upload completed successfully
• 1 - Error occurred (missing arguments, file not found, missing credentials, upload failed, etc.)

Core Concepts

Terminal UI

r2put displays an animated terminal interface with:

• Progress bar with percentage and status
• Transfer statistics (rate, ETA)
• Timestamped log messages
• Presigned download URL on success

See Terminal UI Reference for details.

MIME Type Detection

Automatically detects content types from file extensions. See MIME Detection Reference for supported mappings.

Upload Metadata

Files include metadata:

• uploaded-at: ISO 8601 timestamp
• original-filename: Original filename

See Metadata Reference for details.

Presigned URLs

Generated automatically on successful upload:

• 3600 second (1 hour) expiration
• S3-compatible query parameters
• Immediate access without additional authentication

See Presigned URLs Reference for details.

Documentation Structure

Guides

• Quick Start Guide - Getting started with r2put

Examples

• Real-World Scenarios - Common usage patterns and workflows
• Edge Cases - Advanced scenarios and edge case handling

Reference

• CLI Interface - Complete command-line interface documentation
• Error Handling - Error scenarios and handling
• Terminal UI - Terminal UI output details
• MIME Detection - Content type detection
• Metadata - Upload metadata specification
• Presigned URLs - Presigned URL generation and usage

Requirements

• Node.js runtime
• Cloudflare R2 account with:
  • Account ID
  • R2 API Access Key ID
  • R2 API Secret Access Key
• File system access to read files
• Interactive terminal (for UI display)

Important Notes

Programmatic Usage: r2put is CLI-only and does not export a programmatic API. For programmatic access, use the @cfkit/r2 package directly.

Non-Interactive Environments: Terminal UI may not render correctly in CI/CD. Consider using @cfkit/r2 directly for programmatic control.

Troubleshooting

Common issues and solutions:

• Authentication errors: Verify all three environment variables are set and correct
• File not found: Check file path and permissions
• Terminal UI issues: Ensure terminal supports ANSI escape codes
• Upload hangs: Check network connectivity and R2 service status
• Progress bar incorrect: Progress is simulated for UI purposes

See Error Handling Reference for comprehensive troubleshooting.