CLI Interface Reference

Complete command-line interface documentation for r2put.

Command Syntax

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

Or using short flags:

r2put -f <path> -b <name> [-k <key>] [-r <region>] [-h]

Options

Required Options

--file, -f <path>

Path to file to upload. Can be relative or absolute path.

• Required: Yes
• Type: String (file path)
• Examples:

  r2put --file ./data.bin --bucket my-bucket
  r2put --file /home/user/data.bin --bucket my-bucket
  r2put --file "./my file.bin" --bucket my-bucket

Validation:

• Must point to an existing file (not a directory)
• File must be readable
• Path is validated before upload

--bucket, -b <name>

Target R2 bucket name.

• Required: Yes
• Type: String (bucket name)
• Examples:

  r2put --file ./data.bin --bucket production-v4
  r2put -f ./image.png -b assets

Validation:

• Must be a valid R2 bucket name
• Bucket must exist and be accessible
• Credentials must have write permissions

Optional Options

--key, -k <key>

Custom object key for the uploaded file.

• Required: No
• Type: String (object key)
• Default: Filename from --file path
• Examples:

  r2put --file ./local-image.png --bucket assets --key images/hero.png
  r2put -f ./data.bin -b my-bucket -k "backups/$(date +%Y%m%d).bin"

Behavior:

• If not provided, uses filename from --file path
• Special characters are preserved
• Must be valid for R2 (follows S3 key rules)

--region, -r <region>

Region hint for display purposes.

• Required: No
• Type: String (region code)
• Default: "WNAM"
• Examples:

  r2put --file ./backup.tar.gz --bucket backups --region ENAM
  r2put -f ./data.bin -b my-bucket -r APAC

Behavior:

• Display only; doesn't affect upload
• Used in terminal UI output
• Common values: WNAM, ENAM, APAC, EEUR, WEUR

--help, -h

Show help message and exit.

• Required: No
• Type: Flag (no value)
• Examples:

  r2put --help
  r2put -h

Environment Variables

All environment variables are required:

CLOUDFLARE_ACCOUNT_ID    # Your Cloudflare Account ID
R2_ACCESS_KEY_ID         # R2 API Access Key ID
R2_SECRET_ACCESS_KEY     # R2 API Secret Access Key

Validation:

• All three must be set before invocation
• Tool validates presence before upload
• Missing variables cause exit code 1 with error message

Exit Codes

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

Usage Examples

Basic Upload

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

Upload with Custom Key

r2put -f ./local-image.png -b assets -k images/hero.png

Upload with Region Hint

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

Complete Example

# Set environment variables
export CLOUDFLARE_ACCOUNT_ID="abc123..."
export R2_ACCESS_KEY_ID="xyz789..."
export R2_SECRET_ACCESS_KEY="secret..."

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

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

Argument Validation

The CLI validates all arguments before processing:

• --file must be provided and point to an existing file (not a directory)
• --bucket must be provided and be a valid R2 bucket name
• --key is optional; if not provided, uses filename from --file path
• --region is optional; used only for display purposes
• All environment variables must be set before invocation

Error Messages

Common error messages:

• ERROR: Missing required argument: --file
• ERROR: File not found: /path/to/file
• ERROR: Not a file: /path/to/directory
• ERROR: Missing CLOUDFLARE_ACCOUNT_ID environment variable
• ERROR: Missing R2_ACCESS_KEY_ID environment variable
• ERROR: Missing R2_SECRET_ACCESS_KEY environment variable

See Error Handling Reference for complete error documentation.