raindrop object

The raindrop object command performs object storage operations on Raindrop buckets. Upload files, download objects, delete objects, and list bucket contents directly from the command line.

These commands provide direct access to bucket contents without needing S3 credentials. Use them for quick operations, scripting, and automation.

Bucket Version Syntax

Specify bucket versions using the # separator:

--bucket my-bucket            # Uses version from config
--bucket my-bucket#v1.0.0     # Uses specific version

Basic Usage

Upload a file:

raindrop object put myfile.txt ./local-file.txt --bucket my-bucket

Download a file:

raindrop object get myfile.txt --bucket my-bucket --output ./local-file.txt

List bucket contents:

raindrop object list --bucket my-bucket

Delete an object:

raindrop object delete myfile.txt --bucket my-bucket

Command Reference

raindrop object get

Download an object from a bucket.

Syntax:

raindrop object get <key> --bucket <bucket> [--output <path>]

Arguments:

• <key> - Object key (path) in bucket (required)

Flags:

Flag	Description	Required	Default
-b, --bucket	Bucket name (with optional version)	Yes	-
-o, --output	Output file path	No	stdout

Examples:

# Download to stdout
raindrop object get myfile.txt --bucket my-bucket

# Download to file
raindrop object get myfile.txt --bucket my-bucket --output ./local-file.txt

# Download from specific version
raindrop object get myfile.txt --bucket my-bucket#v1.0.0 --output ./file.txt

# Download from nested path
raindrop object get images/photo.jpg --bucket my-bucket --output ./photo.jpg

Behavior:

Without --output, content is written to stdout. This works well for text files but may produce binary output for other file types.

---

raindrop object put

Upload a file to a bucket.

Syntax:

raindrop object put <key> <file> --bucket <bucket> [--content-type <type>]

Arguments:

• <key> - Object key (path) in bucket (required)
• <file> - Local file path to upload (required)

Flags:

Flag	Description	Required	Default
-b, --bucket	Bucket name (with optional version)	Yes	-
--content-type	MIME content type	No	Auto-detected

Examples:

# Upload file
raindrop object put myfile.txt ./local-file.txt --bucket my-bucket

# Upload with content type
raindrop object put data.json ./data.json --bucket my-bucket --content-type application/json

# Upload to specific version
raindrop object put file.txt ./file.txt --bucket my-bucket#v1.0.0

# Upload to nested path
raindrop object put images/photo.jpg ./photo.jpg --bucket my-bucket

# Upload with explicit content type
raindrop object put archive.bin ./data.bin --bucket my-bucket --content-type application/octet-stream

Content Type Detection:

If --content-type is not specified, the CLI attempts to detect the MIME type from the file extension:

• .txt → text/plain
• .json → application/json
• .html → text/html
• .jpg, .jpeg → image/jpeg
• .png → image/png
• .pdf → application/pdf

For binary files or unknown extensions, specify --content-type explicitly.

---

raindrop object delete

Delete an object from a bucket.

Syntax:

raindrop object delete <key> --bucket <bucket> [--force]

Arguments:

• <key> - Object key (path) to delete (required)

Flags:

Flag	Description	Required	Default
-b, --bucket	Bucket name (with optional version)	Yes	-
-f, --force	Skip confirmation prompt	No	false

Examples:

# Delete with confirmation
raindrop object delete myfile.txt --bucket my-bucket

# Delete without confirmation
raindrop object delete myfile.txt --bucket my-bucket --force

# Delete from specific version
raindrop object delete myfile.txt --bucket my-bucket#v1.0.0 --force

# Delete from nested path
raindrop object delete images/photo.jpg --bucket my-bucket --force

Behavior:

Deletion is permanent and cannot be undone. Always use --force carefully in scripts to avoid accidental data loss.

---

raindrop object list

List objects in a bucket.

Syntax:

raindrop object list --bucket <bucket> [--prefix <prefix>] [--output <format>]

Flags:

Flag	Description	Required	Default
-b, --bucket	Bucket name (with optional version)	Yes	-
--prefix	Filter by key prefix	No	-
-o, --output	Output format	No	table

Output Formats:

• table - Formatted table with columns
• text - Plain text with details per object
• json - JSON array of objects

Examples:

# List all objects
raindrop object list --bucket my-bucket

# List with prefix filter
raindrop object list --bucket my-bucket --prefix images/

# List from specific version
raindrop object list --bucket my-bucket#v1.0.0

# List as JSON
raindrop object list --bucket my-bucket --output json

# List text files only
raindrop object list --bucket my-bucket --prefix documents/ --output table

Output (table format):

┌──────────────────────┬──────────┬──────────────────┬──────────────────────────┐
│ Key                  │ Size     │ Content-Type     │ Last Modified            │
├──────────────────────┼──────────┼──────────────────┼──────────────────────────┤
│ myfile.txt           │ 1024     │ text/plain       │ 2025-10-23T10:30:00.000Z │
│ data.json            │ 512      │ application/json │ 2025-10-23T11:45:00.000Z │
│ images/photo.jpg     │ 204800   │ image/jpeg       │ 2025-10-23T09:15:00.000Z │
└──────────────────────┴──────────┴──────────────────┴──────────────────────────┘

Output (text format):

Key: myfile.txt
  Size: 1024 bytes
  Content-Type: text/plain
  Last Modified: 2025-10-23T10:30:00.000Z
---
Key: data.json
  Size: 512 bytes
  Content-Type: application/json
  Last Modified: 2025-10-23T11:45:00.000Z
---

Common Workflows

Uploading Files

Upload single files or multiple files:

# Upload single file
raindrop object put README.md ./README.md --bucket docs

# Upload with proper content type
raindrop object put api/schema.json ./schema.json --bucket docs --content-type application/json

# Upload multiple files (bash loop)
for file in *.txt; do
  raindrop object put "docs/$file" "$file" --bucket my-bucket
done

Downloading Files

Download files for backup or local processing:

# Download single file
raindrop object get report.pdf --bucket documents --output ./report.pdf

# Download all objects with prefix (requires list + loop)
raindrop object list --bucket my-bucket --prefix images/ --output json | \
  jq -r '.[].key' | \
  while read key; do
    raindrop object get "$key" --bucket my-bucket --output "./$key"
  done

Organizing Objects

Use prefixes to organize objects in a hierarchy:

# Upload to different "directories"
raindrop object put public/index.html ./index.html --bucket website
raindrop object put public/styles/main.css ./main.css --bucket website
raindrop object put assets/images/logo.png ./logo.png --bucket website

# List by directory
raindrop object list --bucket website --prefix public/
raindrop object list --bucket website --prefix assets/images/

Syncing Content

Replace updated files:

# Check existing file
raindrop object get config.json --bucket my-app --output old-config.json

# Upload new version
raindrop object put config.json ./new-config.json --bucket my-app

# Verify upload
raindrop object get config.json --bucket my-app --output verify-config.json

Cleaning Up

Delete old or unwanted objects:

# List objects to identify candidates for deletion
raindrop object list --bucket my-bucket --output table

# Delete specific object
raindrop object delete old-data.csv --bucket my-bucket --force

# Delete multiple objects (bash loop)
for key in file1.txt file2.txt file3.txt; do
  raindrop object delete "$key" --bucket my-bucket --force
done

Backup and Restore

Create backups of bucket contents:

# Backup: Download all objects
mkdir -p backup
raindrop object list --bucket my-bucket --output json | \
  jq -r '.[].key' | \
  while read key; do
    mkdir -p "backup/$(dirname "$key")"
    raindrop object get "$key" --bucket my-bucket --output "backup/$key"
  done

# Restore: Upload from backup
find backup -type f | while read file; do
  key="${file#backup/}"
  raindrop object put "$key" "$file" --bucket my-bucket
done

Scripting Examples

Bulk Upload Script

#!/bin/bash
# upload-directory.sh - Upload entire directory to bucket

BUCKET="my-bucket"
LOCAL_DIR="./data"
PREFIX="uploaded"

find "$LOCAL_DIR" -type f | while read file; do
  relative_path="${file#$LOCAL_DIR/}"
  key="$PREFIX/$relative_path"

  echo "Uploading: $key"
  raindrop object put "$key" "$file" --bucket "$BUCKET"
done

echo "Upload complete!"

Download with Progress

#!/bin/bash
# download-objects.sh - Download objects with progress

BUCKET="my-bucket"
OUTPUT_DIR="./downloads"

mkdir -p "$OUTPUT_DIR"

# Get list of objects
objects=$(raindrop object list --bucket "$BUCKET" --output json | jq -r '.[].key')
total=$(echo "$objects" | wc -l)
current=0

echo "$objects" | while read key; do
  current=$((current + 1))
  echo "[$current/$total] Downloading: $key"

  # Create directory structure
  mkdir -p "$OUTPUT_DIR/$(dirname "$key")"

  # Download object
  raindrop object get "$key" --bucket "$BUCKET" --output "$OUTPUT_DIR/$key"
done

echo "Download complete!"

Conditional Upload

#!/bin/bash
# conditional-upload.sh - Upload only if file doesn't exist or is newer

BUCKET="my-bucket"
LOCAL_FILE="./data.json"
REMOTE_KEY="data.json"

# Check if object exists
if raindrop object get "$REMOTE_KEY" --bucket "$BUCKET" > /tmp/remote-file 2>/dev/null; then
  echo "Object exists, comparing..."

  # Compare files (simplified - just check size)
  local_size=$(wc -c < "$LOCAL_FILE")
  remote_size=$(wc -c < /tmp/remote-file)

  if [ "$local_size" -ne "$remote_size" ]; then
    echo "File changed, uploading..."
    raindrop object put "$REMOTE_KEY" "$LOCAL_FILE" --bucket "$BUCKET"
  else
    echo "File unchanged, skipping upload"
  fi
else
  echo "Object doesn't exist, uploading..."
  raindrop object put "$REMOTE_KEY" "$LOCAL_FILE" --bucket "$BUCKET"
fi

rm -f /tmp/remote-file

Performance Tips

Upload Performance:

• Use appropriate --content-type to avoid detection overhead
• Upload larger files during off-peak hours
• Consider parallel uploads for multiple files (use & in bash)

Download Performance:

• Download to local disk (SSD preferred) for best performance
• Use --output instead of redirecting stdout for large files
• Consider downloading in parallel for multiple objects

Listing Performance:

• Use --prefix to narrow down results
• Use JSON output (--output json) for programmatic processing
• Cache list results when performing multiple operations

Exit Codes

Code	Description
0	Command completed successfully
1	General error (bucket not found, object not found, upload failed, etc.)
2	Invalid arguments