Upload Metadata Reference

Complete documentation of metadata added to uploaded files.

Overview

r2put automatically adds metadata to all uploaded files. This metadata is set on the R2 object and can be retrieved via the R2 API.

Metadata Fields

uploaded-at

ISO 8601 timestamp indicating when the file was uploaded.

• Type: String (ISO 8601 format)
• Example: "2024-01-15T13:53:05.123Z"
• Set At: Upload time
• Format: ISO 8601 with timezone

original-filename

Original filename from the upload.

• Type: String
• Source:
  • Uses value from --key if provided
  • Otherwise uses filename from --file path
• Example: "data.bin" or "images/hero.png"

Metadata Interface

interface UploadMetadata {
  'uploaded-at': string;       // ISO 8601 timestamp
  'original-filename': string; // Original filename from --key argument (or --file path if --key not provided)
}

Behavior

Automatic Addition

Metadata is automatically added to all uploaded files:

• No configuration required
• Always included
• Set during upload process

Source Determination

The original-filename field is determined as follows:

1. If --key is provided: Uses the value from --key

   r2put --file ./local-image.png --bucket assets --key images/hero.png
   # original-filename: "images/hero.png"

2. If --key is not provided: Uses filename from --file path

   r2put --file ./data.bin --bucket my-bucket
   # original-filename: "data.bin"

Timestamp Format

The uploaded-at timestamp:

• Uses ISO 8601 format
• Includes timezone information
• Set at the moment of upload
• Example: "2024-01-15T13:53:05.123Z"

Retrieving Metadata

Metadata is not displayed in the terminal UI output. To retrieve metadata:

Using R2 API

import { R2 } from '@cfkit/r2';

const r2 = new R2({
  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
  accessKeyId: process.env.R2_ACCESS_KEY_ID!,
  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
});

const object = await r2.headObject({
  bucket: 'my-bucket',
  key: 'data.bin',
});

console.log(object.metadata);
// {
//   'uploaded-at': '2024-01-15T13:53:05.123Z',
//   'original-filename': 'data.bin'
// }

Using Cloudflare Dashboard

1. Navigate to R2 in Cloudflare dashboard
2. Select bucket
3. Select object
4. View metadata in object details

Examples

Basic Upload

r2put --file ./data.bin --bucket my-bucket

Metadata:

• uploaded-at: "2024-01-15T13:53:05.123Z" (example)
• original-filename: "data.bin"

Upload with Custom Key

r2put --file ./local-image.png --bucket assets --key images/hero.png

Metadata:

• uploaded-at: "2024-01-15T13:53:05.123Z" (example)
• original-filename: "images/hero.png"

Upload with Path

r2put --file /home/user/documents/file.pdf --bucket my-bucket

Metadata:

• uploaded-at: "2024-01-15T13:53:05.123Z" (example)
• original-filename: "file.pdf" (filename only, not full path)

Use Cases

Tracking Upload Time

Use uploaded-at to:

• Track when files were uploaded
• Sort files by upload time
• Implement retention policies
• Audit file uploads

Preserving Original Filenames

Use original-filename to:

• Track original file names
• Maintain file naming history
• Implement file versioning
• Restore original names

Limitations

Display

• Metadata is not displayed in terminal UI output
• Must use R2 API or dashboard to view metadata

Modification

• Metadata cannot be modified after upload
• Must re-upload file to change metadata

Custom Metadata

• r2put only adds uploaded-at and original-filename
• Cannot add custom metadata fields via r2put
• Use @cfkit/r2 directly for custom metadata

Troubleshooting

Metadata Not Visible

Symptoms:

• Metadata not shown in terminal UI
• Need to verify metadata was set

Resolution:

• Metadata is set on R2 object, not displayed in terminal UI
• Use R2 API or Cloudflare dashboard to view metadata
• Metadata includes uploaded-at and original-filename
• Metadata is available via R2 API after upload completes

Incorrect Original Filename

Symptoms:

• original-filename doesn't match expected value

Resolution:

• If --key provided, original-filename uses --key value
• If --key not provided, original-filename uses filename from --file path
• Full paths are not preserved, only filename is used