Terminal UI Reference

Complete documentation of r2put's terminal user interface.

Overview

r2put displays an animated terminal user interface (TUI) built with React Ink. The UI provides real-time feedback during file upload with animated progress bars, transfer statistics, and timestamped log messages.

UI Components

Header

Cloudflare R2 branding with:

• Centered title: "C L O U D F L A R E R 2"
• Subtitle: "ULTRA-LOW LATENCY OBJECT STORAGE"

File Information

Displays file details in rounded border boxes:

• Filename: Name of the file being uploaded
• File Size: Formatted size (B, KB, MB, or GB)
• MIME Type: Detected content type

Example:

┌─────────┐ ┌─────────────────────────┐
│ 1.0 MB  │ │ application/octet-stream│
└─────────┘ └─────────────────────────┘

Progress Bar

Animated progress bar showing:

• Current Percentage: 0-100%
• Status Label: "UPLOADING" or "TRANSFER COMPLETE"
• Animated Spinner:
  • During upload: ◐ ◓ ◑ ◒ (rotating)
  • When complete: ✔ (checkmark)
• Visual Bar:
  • Filled characters: █
  • Empty characters: ░
  • Adapts width to terminal size

Example:

◐ UPLOADING                                                67%
█████████████████████████████████████████████░░░░░░░░░░░░░░░░░

Transfer Statistics

Two rounded border boxes displaying:

• Transfer Rate: Formatted as B/S, KB/S, MB/S, or GB/S
• Estimated Time Remaining:
  • Less than 1 second: "< 1S"
  • Seconds: "Ns"
  • Minutes and seconds: "M M Ss"
  • Hours and minutes: "H H Mm"

Example:

┌──────────────────────────┐ ┌──────────────────────┐
│ TRANSFER RATE: 8.4 MB/S  │ │ EST. TIME: 4S        │
└──────────────────────────┘ └──────────────────────┘

Log Messages

Timestamped log entries with:

• Timestamp: [HH:MM:SS] format
• Animated Typing Effect: Latest message types out (3 chars per 15ms)
• Color-coded Prefixes:
  • › for info messages
  • ✔ for success messages
• Animated Cursor: ▌ during typing
• Bucket and Region Header: Shows bucket name and region hint

Example:

╭───────────────────────────────────────────────────────────╮
│ ◘ BUCKET: production-v4                                   │
│ ◈ REGION: WNAM                                            │
│                                                           │
│ [13:53:02] › Initializing secure handshake with R2-E1...        │
│ [13:53:02] › Payload delivered. Starting edge-layer optimization. │
│ [13:53:05] ✔ Transfer complete. Resource available at edge node. │
╰───────────────────────────────────────────────────────────╯

Success Result

Upon successful upload, displays:

• Object Path: Format bucket/objectKey
• Presigned Download URL: Valid for 1 hour, includes all query parameters

Example:

› OBJECT PATH: production-v4/data.bin
› DOWNLOAD URL:
https://production-v4.abc123.r2.cloudflarestorage.com/data.bin?X-Amz-...

Complete Example Output

C L O U D F L A R E   R 2
ULTRA-LOW LATENCY OBJECT STORAGE

› Uploading: data.bin
┌─────────┐ ┌─────────────────────────┐
│ 1.0 MB  │ │ application/octet-stream│
└─────────┘ └─────────────────────────┘

◐ UPLOADING                                                67%
█████████████████████████████████████████████░░░░░░░░░░░░░░░░░

┌──────────────────────────┐ ┌──────────────────────┐
│ TRANSFER RATE: 8.4 MB/S  │ │ EST. TIME: 4S        │
└──────────────────────────┘ └──────────────────────┘

╭───────────────────────────────────────────────────────────╮
│ ◘ BUCKET: production-v4                                   │
│ ◈ REGION: WNAM                                            │
│                                                           │
│ [13:53:02] › Initializing secure handshake with R2-E1...        │
│ [13:53:02] › Payload delivered. Starting edge-layer optimization. │
│ [13:53:05] ✔ Transfer complete. Resource available at edge node. │
╰───────────────────────────────────────────────────────────╯

› OBJECT PATH: production-v4/data.bin
› DOWNLOAD URL:
https://production-v4.abc123.r2.cloudflarestorage.com/data.bin?X-Amz-...

UI Considerations

Terminal Requirements

• Interactive Terminal: Required for UI display
• ANSI Escape Codes: Terminal must support ANSI escape codes
• Color Support: Recommended for best experience
• Terminal Size: UI adapts to terminal width (progress bar adjusts)

Limitations

• Non-Interactive Environments: Terminal UI may not render correctly in CI/CD
• Output Blocking: UI blocks terminal output during execution
• Terminal Emulator Compatibility: May not render correctly in all terminal emulators
• Progress Simulation: Progress bar shows simulated progress, not actual upload progress

Non-Interactive Use

For non-interactive environments:

• Terminal UI still renders (may not display correctly)
• Exit codes work correctly
• Output can be redirected (UI may not render correctly)
• Consider using @cfkit/r2 directly for programmatic control

Progress Bar Behavior

Important Notes:

• Progress is simulated, not actual upload progress
• Progress bar is for UI purposes only
• Actual upload may complete before progress reaches 100%
• This is expected behavior

The simulated progress provides visual feedback but does not reflect the actual upload state. The upload completes when the R2 API confirms success, regardless of progress bar percentage.

Error Display

Errors are displayed in the terminal UI:

• Red Border Box: For upload errors
• Error Message: From R2 client or tool validation
• Help Suggestion: For argument errors

Error messages are clearly visible and provide actionable information for resolution.