cloudflare-r2-cli 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61fad913620eba6d2c642b7d1b8d82dca3598d429fbc96d0304b9b732647b139
-  data.tar.gz: 85a0718c8c066018a21f5603f279c30ff1572ed57d5d7e323b2e5692a3b00d63
+  metadata.gz: 3195ca7161952b3ef9a5e7cc6e6d1afb4af82c631364a6786f4b1d4aeaace272
+  data.tar.gz: ca9017f232ee7a6a8a15048dfc6dd895e490f9ac18eb442dfb7e518deb89830d
 SHA512:
-  metadata.gz: 4879d8be86b64e6a2dfd8230cca78d4f20844ad3dc1955369b01a4f61e87aedf6c22c75aa34746945aa8d23a3cf91dfc4dc903fec612c49f6446de9009f6b632
-  data.tar.gz: 4705537941cfe7918ee1885aef24707f9a23cbf8cd799925eb50cb91def26267d6dc77c9a49d8127c625eec5eb65f95fdcbe0a5070c1c2dec1a380d4c5db40d3
+  metadata.gz: 7166d020132b6cabf2835a41a8cca93531eb58e4b65102ca8f9d8b9a16b9055eb460578f346a4b38cf15e757d3f5581e14da22eaf2b3b893497deabfb4de53d8
+  data.tar.gz: 331b10be069ca8262aceb8ebffebddaedc99c4cf806a4ff35eae5679eeed7304ef7b64079f7d4e66d4c4370767d6859f8e9cce72b776cf1f745bc38c6c88ff78

data/CHANGELOG.md

@@ -3,7 +3,65 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.2.0] - 2026-09-21
+
+### Added
+
+* `r2 exists` — checks whether an object exists in the configured bucket,
+  exiting with status code `1` when it does not.
+* `r2 list --prefix` — lists only the objects whose keys start with the given
+  prefix.
+* `r2 delete --force` — deletes an object without asking for confirmation.
+* Automatic `Content-Type` definition on upload, based on the object key.
+* Automatic retries with exponential backoff for transient network failures
+  in every storage operation.
+* `R2::ContentType` — maps the object key extension to a content type.
+* `R2::Retry` — retry policy with exponential backoff shared by the storage
+  operations.
+* `R2::Errors::ConfirmationRequiredError` and `R2::Errors::AbortedError`.
+
+### Changed
+
+* `r2 delete` now asks for confirmation before deleting. In non-interactive
+  executions (scripts and pipelines) the deletion requires `--force`.
+* `r2 list` now follows the pagination of the bucket, listing every object
+  instead of only the first page.
+* `Storage#list` accepts a `prefix` and lists every page of the bucket.
+* `Storage#upload` accepts an explicit `content_type` and rewinds the streamed
+  content before every attempt.
+* `Storage#exists?` — checks the existence of an object using its metadata.
+* Restructured the documentation to cover the new commands, options and
+  reliability behavior.
+
+## [1.2.0] - 2026-09-21
+
+### Added
+
+* `r2 exists` — checks whether an object exists in the configured bucket,
+  exiting with status code `1` when it does not.
+* `r2 list --prefix` — lists only the objects whose keys start with the given
+  prefix.
+* `r2 delete --force` — deletes an object without asking for confirmation.
+* Automatic `Content-Type` definition on upload, based on the object key.
+* Automatic retries with exponential backoff for transient network failures
+  in every storage operation.
+* `R2::ContentType` — maps the object key extension to a content type.
+* `R2::Retry` — retry policy with exponential backoff shared by the storage
+  operations.
+* `R2::Errors::ConfirmationRequiredError` and `R2::Errors::AbortedError`.
+
+### Changed
+
+* `r2 delete` now asks for confirmation before deleting. In non-interactive
+  executions (scripts and pipelines) the deletion requires `--force`.
+* `r2 list` now follows the pagination of the bucket, listing every object
+  instead of only the first page.
+* `Storage#list` accepts a `prefix` and lists every page of the bucket.
+* `Storage#upload` accepts an explicit `content_type` and rewinds the streamed
+  content before every attempt.
+* `Storage#exists?` — checks the existence of an object using its metadata.
+* Restructured the documentation to cover the new commands, options and
+  reliability behavior.
 
 ## [1.1.0] - 2026-09-09
 
@@ -45,6 +103,7 @@ First stable release of `cloudflare-r2-cli`.
 * Unit, integration and E2E test suites.
 * Continuous integration via GitHub Actions.
 
-[Unreleased]: https://github.com/rpzerosixcode/cloudflare-r2-cli/compare/v1.1.0...HEAD
+[Unreleased]: https://github.com/rpzerosixcode/cloudflare-r2-cli/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/rpzerosixcode/cloudflare-r2-cli/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/rpzerosixcode/cloudflare-r2-cli/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/rpzerosixcode/cloudflare-r2-cli/releases/tag/v1.0.0

data/README.md

@@ -12,7 +12,9 @@ Ruby CLI to manage objects on Cloudflare R2 from the terminal.
   * [Download](#download)
   * [Delete](#delete)
   * [List](#list)
+  * [Exists](#exists)
   * [Global Options](#global-options)
+* [Reliability](#reliability)
 * [Testing](#testing)
 * [Changelog](#changelog)
 * [License](#license)
@@ -37,7 +39,7 @@ $ git clone https://github.com/rpzerosixcode/cloudflare-r2-cli.git
 $ cd cloudflare-r2-cli
 $ bundle install
 $ bundle exec rake build
-$ gem install pkg/cloudflare-r2-cli-1.1.0.gem
+$ gem install pkg/cloudflare-r2-cli-1.2.0.gem
 ```
 
 ## Configuration
@@ -68,7 +70,7 @@ $ r2 upload ./images/photo.png
 $ r2 upload ./images/photo.png --key uploads/photo.png
 ```
 
-By default, the object key in the bucket is the name of the given file. Use `--key` to store the object under a custom key. On success, a confirmation message is displayed.
+By default, the object key in the bucket is the name of the given file. Use `--key` to store the object under a custom key. The `Content-Type` of the object is defined automatically from its key extension (`application/octet-stream` when the extension is unknown). On success, a confirmation message is displayed.
 
 ### Download
 
@@ -87,9 +89,17 @@ Deletes a file stored in the configured bucket:
 
 ```console
 $ r2 delete image.jpg
+$ r2 delete image.jpg --force
 ```
 
-On success, a confirmation message is displayed.
+The deletion is confirmed before the request is sent:
+
+```console
+$ r2 delete image.jpg
+Delete "image.jpg" from the bucket? [y/N]
+```
+
+The operation only proceeds with an affirmative answer (`y` or `yes`). Use `--force` to delete without confirmation, which is required in non-interactive executions, such as scripts and pipelines, where the confirmation cannot be requested. On success, a confirmation message is displayed.
 
 ### List
 
@@ -97,6 +107,26 @@ Lists the files stored in the configured bucket:
 
 ```console
 $ r2 list
+$ r2 list --prefix uploads/
+```
+
+Every object is listed, following the pagination of the bucket. Use `--prefix` to list only the objects whose keys start with the given prefix.
+
+### Exists
+
+Checks whether an object exists in the configured bucket:
+
+```console
+$ r2 exists image.jpg
+```
+
+The exit status is `0` when the object exists and `1` when it does not, which allows the command to be used in scripts:
+
+```console
+$ r2 exists image.jpg
+Object exists: image.jpg
+$ r2 exists missing.jpg
+Object not found: missing.jpg
 ```
 
 ### Global Options
@@ -107,11 +137,24 @@ Every command accepts the global `--verbose` flag, which writes detailed diagnos
 $ r2 list --verbose
 $ r2 upload image.jpg --verbose
 $ r2 download image.jpg --verbose
-$ r2 delete image.jpg --verbose
+$ r2 delete image.jpg --force --verbose
+$ r2 exists image.jpg --verbose
 ```
 
 On any error, the CLI displays the corresponding message on the error output and exits with status code `1`.
 
+## Reliability
+
+### Automatic retries
+
+Requests that fail due to transient network failures are retried automatically with exponential backoff: 3 attempts in total, waiting 0.5s and then 1s between them, capped at 5s. Failures that are not transient, such as missing credentials or an invalid bucket, are reported immediately.
+
+The retries are applied to every storage operation and restart from the beginning of the data: uploaded content is rewound and downloaded content is written from the start again, so a retried request never uploads an empty body or leaves a partially written file.
+
+### Pagination
+
+`r2 list` follows the pagination of the bucket, requesting every page until the last one, so all objects are listed regardless of the amount of keys in the bucket.
+
 ## Testing
 
 Run the full suite (unit, integration and E2E):

data/docs/ARCHITECTURE.md

@@ -15,6 +15,8 @@ Built with `thor`. Acts as a minimal orchestrator:
 
 The CLI contains no business rules and does not access files or `ENV` directly.
 
+Commands that delete data ask for confirmation before delegating the operation. The confirmation is requested only when the standard input is a terminal, and `--force` skips it, so non-interactive executions must opt out explicitly.
+
 ### Configuration
 
 `lib/r2/configuration.rb`
@@ -36,10 +38,11 @@ Wraps `aws-sdk-s3` to communicate with the S3-compatible Cloudflare R2 endpoint.
 
 Responsible only for:
 
-* Uploading objects.
+* Uploading objects, defining the content type from the object key.
 * Downloading objects.
 * Deleting objects.
-* Listing objects.
+* Listing objects, following the pagination of the bucket and filtering by prefix.
+* Checking whether an object exists.
 
 `Storage` does not:
 
@@ -50,6 +53,31 @@ Responsible only for:
 
 The bucket is provided by `Configuration` rather than passed to individual operations.
 
+Every request is wrapped in the retry support (see `Retry`), so transient network failures are retried before the failure reaches the caller.
+
+### Content Type
+
+`lib/r2/content_type.rb`
+
+Defines the content type of an object from the extension of its key:
+
+* `ContentType.for(key)` returns the mapped type, or `application/octet-stream` when the extension is not mapped.
+* The comparison is case insensitive, and keys inside directories are supported.
+
+`Storage#upload` uses this value automatically and accepts an explicit `content_type` when the caller needs to override it.
+
+### Retry
+
+`lib/r2/retry.rb`
+
+Concentrates the automatic retries of the application:
+
+* `Policy` holds the retry settings: total attempts, base delay and maximum delay.
+* `Retry.call` runs the block and retries only the error classes informed as transient, waiting between the attempts with exponential backoff.
+* The waiting strategy and the logger are injected, keeping the behavior testable without real waiting.
+
+`Storage` uses a shared policy for every operation and passes `Seahorse::Client::NetworkingError` as the transient error, which is also the error mapped to `NetworkError`.
+
 ### Errors
 
 `lib/r2/errors.rb`
@@ -64,6 +92,11 @@ All errors inherit from `R2::Errors::Error`. Exceptions raised by `aws-sdk-s3` a
 * `NetworkError`
 * `StorageError`
 
+Errors of the CLI are also part of the domain:
+
+* `ConfirmationRequiredError` when a destructive operation cannot be confirmed in a non-interactive execution.
+* `AbortedError` when the user does not confirm a destructive operation.
+
 This prevents callers from depending on AWS SDK-specific exceptions.
 
 The CLI rescues the base `Error`, prints the message to `stderr`, and exits with a non-zero status.
@@ -88,26 +121,36 @@ CLI
  │
  ├── Logging ←── --verbose
  │
- └── Storage ──→ aws-sdk-s3 ──→ Cloudflare R2
-                      │
-                      └── failure → R2::Errors::*
-                                      │
-                                      └── CLI → stderr + exit 1
+ ├── $stdin ←── confirmation of destructive commands
+ │
+ └── Storage
+      │
+      ├── ContentType ──→ Content-Type of the object
+      │
+      └── Retry ──→ aws-sdk-s3 ──→ Cloudflare R2
+                       │
+                       └── failure → R2::Errors::*
+                                       │
+                                       └── CLI → stderr + exit 1
 ```
 
+Transient network failures are retried by `Retry` before the error mapping, so a brief instability does not interrupt the operation.
+
 ## Testing
 
 ### Unit Tests
 
 `spec/unit/`
 
-Tests individual components in isolation.
+Tests individual components in isolation: CLI, configuration, content type, errors, logging, retry and storage.
 
 ### Integration Tests
 
 `spec/integration/`
 
-Tests the interaction between the CLI and `Storage` using a fake S3 client.
+Tests the interaction between the CLI and `Storage` using a fake S3 client, which reproduces the bucket behavior, including the pagination of the listing and the metadata requests.
+
+The confirmation prompts are validated with a controlled standard input, so the suite never waits for a real user and the result does not depend on whether the runner has a terminal attached.
 
 ### End-to-End Tests
 
@@ -121,7 +164,19 @@ These tests are skipped when the required credentials are unavailable.
 
 ### Direct Constructor Injection
 
-No dependency-injection container is used. Dependencies are passed directly through constructors, keeping the architecture simple and explicit.
+No dependency-injection container is used. Dependencies are passed directly through constructors, keeping the architecture simple and explicit. `Storage`, for instance, receives its logger, retry policy and waiting strategy, which makes the retries testable without real waiting.
+
+### Deletion Confirmation
+
+Destructive commands confirm the operation before sending it, since a deletion cannot be undone. The confirmation depends on an interactive input, so scripts and pipelines must use `--force`: the alternative, deleting silently when no terminal is attached, would make accidental deletions possible in automated executions.
+
+### Retries with Backoff
+
+Transient network failures are retried with exponential backoff by the application, on top of the retries already performed by `aws-sdk-s3`. Keeping the behavior in the project makes it explicit, configurable and covered by the tests, instead of being an undocumented side effect of the SDK.
+
+### Automatic Content Type
+
+The content type is derived from the object key instead of the local file, because the key is what defines the object in the bucket and can differ from the name of the uploaded file (`--key`). Unmapped extensions fall back to `application/octet-stream`, the default of S3-compatible services.
 
 ### R2 Region
 

data/docs/FEATURES.md

@@ -23,6 +23,7 @@ $ r2 upload ./images/photo.png --key uploads/photo.png
 * Validates that the given file exists.
 * Validates that the path is not a directory.
 * Opens the file in binary read mode.
+* Defines the `Content-Type` of the object from the extension of its key, falling back to `application/octet-stream` when the extension is not mapped.
 * Uploads the content to the configured Cloudflare R2 bucket.
 * Uses the file name as the object key in the bucket, or the custom key given via `--key`.
 * Displays a success message after the upload.
@@ -62,23 +63,40 @@ Deletes a file stored in the configured Cloudflare R2 bucket.
 **Usage:**
 
 ```console
-$ r2 delete <file>
+$ r2 delete <file> [--force]
 ```
 
-**Example:**
+**Examples:**
 
 ```console
 $ r2 delete image.jpg
+$ r2 delete image.jpg --force
 ```
 
 **Behavior:**
 
 * Receives the name of the file to delete.
+* Asks for the confirmation of the deletion before sending the request, unless `--force` is given.
 * Uses the file name as the object key.
 * Requests the object deletion from Cloudflare R2.
 * Considers the operation successful when the storage completes the request without errors.
 * Displays a success message after the operation.
 
+**Confirmation:**
+
+The prompt is written to the standard output and the answer is read from the standard input:
+
+```console
+$ r2 delete image.jpg
+Delete "image.jpg" from the bucket? [y/N]
+```
+
+The deletion only proceeds with an affirmative answer (`y` or `yes`); any other answer, including an empty one, aborts the operation. In non-interactive executions, such as scripts and pipelines, the confirmation cannot be requested, so the CLI aborts with an explanatory message and status code `1`. Use `--force` to delete without confirmation:
+
+```console
+$ r2 delete image.jpg --force
+```
+
 The feature does not perform a follow-up query to check that the object no longer exists. The success confirmation is based on the result of the deletion operation provided by the storage layer.
 
 On error, the corresponding message is displayed and the CLI exits with a non-zero status code.
@@ -89,18 +107,75 @@ Lists the files stored in the configured Cloudflare R2 bucket.
 
 **Usage:**
 
+```console
+$ r2 list [--prefix <prefix>]
+```
+
+**Examples:**
+
 ```console
 $ r2 list
+$ r2 list --prefix uploads/
 ```
 
 **Behavior:**
 
 * Queries the objects stored in the configured bucket.
+* Follows the pagination of the bucket, requesting every page until the last one, so all objects are returned.
+* Lists only the objects whose keys start with the given prefix, when `--prefix` is used.
 * Displays the files found.
-* Returns all objects without pagination or control over the amount of returned objects.
 
 On error, the corresponding message is displayed and the CLI exits with a non-zero status code.
 
+## Exists
+
+Checks whether an object exists in the configured Cloudflare R2 bucket.
+
+**Usage:**
+
+```console
+$ r2 exists <key>
+```
+
+**Examples:**
+
+```console
+$ r2 exists image.jpg
+```
+
+**Behavior:**
+
+* Requests the metadata of the object, instead of its content, so the check does not depend on the object size.
+* Displays `Object exists: <key>` and exits with status code `0` when the object exists.
+* Displays `Object not found: <key>` and exits with status code `1` when the object does not exist, allowing the command to be used in scripts.
+
+On error, the corresponding message is displayed and the CLI exits with a non-zero status code.
+
+## Reliability
+
+### Automatic retries
+
+Transient failures while communicating with Cloudflare R2, such as brief network instabilities, are retried automatically with exponential backoff:
+
+| Attempt | Wait before the attempt |
+| ------- | ----------------------- |
+| 1       | —                       |
+| 2       | 0.5s                    |
+| 3       | 1s                      |
+
+The wait is capped at 5s, and the operation fails after the last attempt, reporting the mapped domain error. Failures that are not transient, such as missing credentials, an invalid bucket or a missing object, are reported immediately, without retries.
+
+The retries are applied to every storage operation and restart from the beginning of the data: the uploaded content is rewound and the downloaded content is written from the start again, so a retried request never sends an incomplete body or leaves a partially written file.
+
+### Diagnostics
+
+With `--verbose`, every retry is reported on the error output with the operation, the failure cause and the wait applied:
+
+```console
+$ r2 upload image.jpg --verbose
+Retrying upload of image.jpg in 0.5s (attempt 2 of 3) after a transient failure: Seahorse::Client::NetworkingError: ...
+```
+
 ## Global Options
 
 Every command accepts the global `--verbose` flag, which writes detailed diagnostic information to the error output without changing the standard output:
@@ -108,6 +183,9 @@ Every command accepts the global `--verbose` flag, which writes detailed diagnos
 ```console
 $ r2 list --verbose
 $ r2 upload image.jpg --verbose
+$ r2 download image.jpg --verbose
+$ r2 delete image.jpg --force --verbose
+$ r2 exists image.jpg --verbose
 ```
 
 Without the flag, diagnostics are discarded by a null logger and only the standard output is produced.

data/docs/SECURITY.md

@@ -9,6 +9,10 @@ The project follows the following security practices:
 - **Isolated test environment** — E2E tests use a dedicated bucket
   (`R2_TEST_BUCKET`) separated from the default application bucket.
 
+- **Confirmation of destructive operations** — `r2 delete` asks for
+  confirmation before deleting and requires `--force` in non-interactive
+  executions, avoiding accidental deletions in scripts and pipelines.
+
 - **Ignored environment files** — `.env` files are excluded from version
   control. Only the `.env.example` template is versioned.
 

data/lib/r2/cli.rb

@@ -124,13 +124,23 @@ module R2
         end
 
         desc "delete FILE", "Deletes a file from R2"
+        method_option :force,
+                      type: :boolean,
+                      default: false,
+                      desc: "Deletes without asking for confirmation"
 
         long_desc <<~LONGDESC
             Deletes a file from the configured Cloudflare R2 bucket.
 
+            The deletion is confirmed before the request is sent. Since a
+            non-interactive execution cannot ask the user, it requires the
+            --force option to proceed.
+
             Examples:
 
               $ r2 delete image.jpg
+
+              $ r2 delete image.jpg --force
         LONGDESC
 
         # Deletes a file from the configured Cloudflare R2 bucket.
@@ -141,6 +151,7 @@ module R2
         # @param file [String] name of the file to delete
         def delete(file)
             logger.debug("Starting delete: #{file.inspect}.")
+            confirm_deletion(file)
             storage.delete(key: file)
             puts "Deleted successfully: #{file}"
             logger.debug("Finished delete: #{file.inspect}.")
@@ -150,19 +161,28 @@ module R2
         end
 
         desc "list", "Lists the files stored in R2"
+        method_option :prefix,
+                      type: :string,
+                      desc: "Lists only the objects whose keys start with the given prefix"
 
         long_desc <<~LONGDESC
             Lists the files stored in the configured Cloudflare R2 bucket.
 
+            Every object is listed, following the pagination of the bucket.
+            Use --prefix to list only the objects whose keys start with the
+            given prefix.
+
             Examples:
 
               $ r2 list
+
+              $ r2 list --prefix uploads/
         LONGDESC
 
         # Lists the files stored in the configured Cloudflare R2 bucket.
         def list
-            logger.debug("Starting list.")
-            files = storage.list
+            logger.debug("Starting list: prefix=#{options[:prefix].inspect}.")
+            files = storage.list(prefix: options[:prefix])
 
             files.each do |file|
                 puts file
@@ -173,6 +193,38 @@ module R2
             exit 1
         end
 
+        desc "exists KEY", "Checks whether an object exists in R2"
+
+        long_desc <<~LONGDESC
+            Checks whether an object exists in the configured Cloudflare R2
+            bucket. The exit status is 0 when the object exists and 1 when it
+            does not, which allows the command to be used in scripts.
+
+            Examples:
+
+              $ r2 exists image.jpg
+        LONGDESC
+
+        # Checks whether an object exists in the configured Cloudflare R2
+        # bucket.
+        #
+        # @param key [String] object key in the bucket
+        def exists(key)
+            logger.debug("Starting existence check: #{key.inspect}.")
+
+            if storage.exists?(key: key)
+                puts "Object exists: #{key}"
+                logger.debug("Finished existence check: #{key.inspect} exists.")
+            else
+                puts "Object not found: #{key}"
+                logger.debug("Finished existence check: #{key.inspect} does not exist.")
+                exit 1
+            end
+        rescue Errors::Error => e
+            warn "Error: #{e.message}"
+            exit 1
+        end
+
         private
 
         # Opens the given file for reading.
@@ -269,5 +321,62 @@ module R2
 
             raise Errors::PermissionError, "Permission denied to write the file: #{destination}"
         end
+
+        # Asks the user to confirm the deletion of an object.
+        #
+        # The confirmation is skipped when `--force` is given. Without it the
+        # deletion only happens after an affirmative answer, which requires an
+        # interactive input: scripts and pipelines cannot be asked, so they
+        # must opt out explicitly, avoiding accidental deletions.
+        #
+        # @param key [String] object key in the bucket
+        # @raise [Errors::ConfirmationRequiredError] when the input is not
+        #   interactive and `--force` was not given
+        # @raise [Errors::AbortedError] when the deletion is not confirmed
+        def confirm_deletion(key)
+            if options[:force]
+                logger.debug("Skipping the deletion confirmation: --force was given.")
+                return
+            end
+
+            raise Errors::ConfirmationRequiredError, confirmation_required_message(key) unless interactive_input?
+
+            return if affirmative?(ask_deletion_confirmation(key))
+
+            raise Errors::AbortedError, "Deletion aborted: #{key}"
+        end
+
+        # Writes the deletion confirmation prompt and reads the answer.
+        #
+        # @param key [String] object key in the bucket
+        # @return [String, nil] answer given by the user
+        def ask_deletion_confirmation(key)
+            $stdout.print("Delete #{key.inspect} from the bucket? [y/N] ")
+            $stdin.gets
+        end
+
+        # Indicates whether the standard input can be used to ask the user.
+        #
+        # @return [Boolean] true when the input is a terminal
+        def interactive_input?
+            $stdin.respond_to?(:tty?) && $stdin.tty?
+        end
+
+        # Indicates whether the given answer confirms the operation.
+        #
+        # @param answer [String, nil] answer given by the user
+        # @return [Boolean] true when the answer is affirmative
+        def affirmative?(answer)
+            answer.to_s.strip.match?(/\Ay(es)?\z/i)
+        end
+
+        # Builds the message shown when the confirmation cannot be requested.
+        #
+        # @param key [String] object key in the bucket
+        # @return [String] message explaining how to proceed
+        def confirmation_required_message(key)
+            "Deletion of #{key} requires confirmation. Run the command in an " \
+                "interactive terminal or use --force to delete it without confirmation."
+        end
     end
 end

data/lib/r2/content_type.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module R2
+    # Determines the content type of an object from its key.
+    #
+    # The mapping covers the formats commonly handled by the CLI. Keys whose
+    # extension is not mapped fall back to the generic binary type, which is
+    # the same behavior offered by S3-compatible services.
+    #
+    # Reference: https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/MIME_types
+    module ContentType
+        # Content type used when the object extension is not mapped.
+        DEFAULT = "application/octet-stream"
+
+        # Content types by file extension.
+        TYPES = {
+            ".avif" => "image/avif",
+            ".bmp" => "image/bmp",
+            ".csv" => "text/csv",
+            ".doc" => "application/msword",
+            ".docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+            ".gif" => "image/gif",
+            ".gz" => "application/gzip",
+            ".htm" => "text/html",
+            ".html" => "text/html",
+            ".ico" => "image/vnd.microsoft.icon",
+            ".jpeg" => "image/jpeg",
+            ".jpg" => "image/jpeg",
+            ".js" => "text/javascript",
+            ".json" => "application/json",
+            ".md" => "text/markdown",
+            ".mp3" => "audio/mpeg",
+            ".mp4" => "video/mp4",
+            ".pdf" => "application/pdf",
+            ".png" => "image/png",
+            ".svg" => "image/svg+xml",
+            ".tar" => "application/x-tar",
+            ".tif" => "image/tiff",
+            ".tiff" => "image/tiff",
+            ".txt" => "text/plain",
+            ".wav" => "audio/wav",
+            ".webp" => "image/webp",
+            ".xls" => "application/vnd.ms-excel",
+            ".xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+            ".xml" => "application/xml",
+            ".yaml" => "application/yaml",
+            ".yml" => "application/yaml",
+            ".zip" => "application/zip"
+        }.freeze
+
+        # Determines the content type of the given object key.
+        #
+        # The extension is compared in lowercase, so keys stored with
+        # uppercase names are also recognized.
+        #
+        # @param key [String] object key in the bucket
+        # @return [String] content type corresponding to the key extension
+        def self.for(key)
+            TYPES.fetch(extension(key), DEFAULT)
+        end
+
+        # Extracts the extension of the given object key.
+        #
+        # @param key [String] object key in the bucket
+        # @return [String] lowercase extension, including the leading dot
+        def self.extension(key)
+            File.extname(key.to_s).downcase
+        end
+    end
+end

data/lib/r2/errors.rb

@@ -42,5 +42,14 @@ module R2
         # Unclassified failure in the storage layer.
         class StorageError < Error
         end
+
+        # The confirmation required before a destructive operation could not
+        # be requested, because the execution is not interactive.
+        class ConfirmationRequiredError < Error
+        end
+
+        # The user did not confirm a destructive operation.
+        class AbortedError < Error
+        end
     end
 end

data/lib/r2/retry.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module R2
+    # Automatic retries with exponential backoff.
+    #
+    # Transient failures, such as brief network instabilities, are retried a
+    # limited number of times. The wait between the attempts grows
+    # exponentially and is capped, so the remote service has time to recover
+    # without making the user wait indefinitely.
+    #
+    # Only the error classes informed as transient are retried; every other
+    # failure is raised immediately, preserving the domain error mapping.
+    module Retry
+        # Total number of attempts: the first execution plus the retries.
+        DEFAULT_MAX_ATTEMPTS = 3
+
+        # Wait applied after the first failed attempt, in seconds.
+        DEFAULT_BASE_DELAY = 0.5
+
+        # Upper limit of the wait between attempts, in seconds.
+        DEFAULT_MAX_DELAY = 5.0
+
+        # Waiting strategy used when nothing else is provided.
+        DEFAULT_SLEEPER = ->(seconds) { sleep(seconds) }
+
+        # Description used in the diagnostics when the caller gives none.
+        DEFAULT_DESCRIPTION = "operation"
+
+        # Retry settings shared by the operations of a client.
+        class Policy
+            attr_reader :max_attempts, :base_delay, :max_delay
+
+            # @param max_attempts [Integer] total number of attempts
+            # @param base_delay [Float] wait after the first failure, in seconds
+            # @param max_delay [Float] upper limit of the wait, in seconds
+            def initialize(
+                max_attempts: DEFAULT_MAX_ATTEMPTS,
+                base_delay: DEFAULT_BASE_DELAY,
+                max_delay: DEFAULT_MAX_DELAY
+            )
+                @max_attempts = max_attempts
+                @base_delay = base_delay
+                @max_delay = max_delay
+            end
+
+            # Wait applied after the given failed attempt.
+            #
+            # @param attempt [Integer] number of the attempt that just failed
+            # @return [Float] seconds to wait before the next attempt
+            def delay_for(attempt)
+                [@base_delay * (2**(attempt - 1)), @max_delay].min
+            end
+        end
+
+        # Runs the block, retrying the transient failures it raises.
+        #
+        # @param policy [Policy] retry settings
+        # @param retry_on [Array<Class>] error classes considered transient
+        # @param logger [#debug, nil] logger used for diagnostics
+        # @param sleeper [#call, nil] waiting strategy used between attempts
+        # @param description [String, nil] operation description used in the diagnostics
+        # @yield the operation to run
+        # @return [Object] result of the block
+        # @raise [StandardError] error of the last attempt when the retries are exhausted
+        def self.call(policy: Policy.new, retry_on: [], logger: nil, sleeper: nil, description: nil)
+            attempt = 0
+            description ||= DEFAULT_DESCRIPTION
+
+            begin
+                attempt += 1
+                yield
+            rescue StandardError => e
+                raise unless transient?(e, retry_on) && attempt < policy.max_attempts
+
+                delay = policy.delay_for(attempt)
+                logger&.debug(retry_message(attempt, policy, description, e, delay))
+                (sleeper || DEFAULT_SLEEPER).call(delay)
+                retry
+            end
+        end
+
+        # Indicates whether an error is considered transient.
+        #
+        # @param error [StandardError] error raised by the operation
+        # @param retry_on [Array<Class>] error classes considered transient
+        # @return [Boolean] true when the failure may be retried
+        def self.transient?(error, retry_on)
+            retry_on.any? { |error_class| error.is_a?(error_class) }
+        end
+
+        # Builds the diagnostic message of a retry.
+        #
+        # @param attempt [Integer] number of the attempt that just failed
+        # @param policy [Policy] retry settings
+        # @param description [String] description of the operation
+        # @param error [StandardError] error raised by the attempt
+        # @param delay [Float] seconds to wait before the next attempt
+        # @return [String] message describing the retry
+        def self.retry_message(attempt, policy, description, error, delay)
+            "Retrying #{description} in #{delay}s (attempt #{attempt + 1} of " \
+                "#{policy.max_attempts}) after a transient failure: " \
+                "#{error.class}: #{error.message}"
+        end
+    end
+end

data/lib/r2/storage.rb

@@ -1,22 +1,34 @@
 # frozen_string_literal: true
 
 require "aws-sdk-s3"
+require_relative "content_type"
 require_relative "errors"
 require_relative "logging"
+require_relative "retry"
 
 module R2
     # Storage layer responsible for communicating with Cloudflare R2.
     #
     # Uses the `aws-sdk-s3` gem with the S3-compatible endpoint provided by
     # the application configuration.
+    #
+    # Transient network failures are retried with exponential backoff
+    # (see `R2::Retry`), so brief instabilities do not fail the operation.
     class Storage
+        # Error classes considered transient and therefore retried.
+        RETRYABLE_ERRORS = [Seahorse::Client::NetworkingError].freeze
+
         # Initializes the storage with the configured credentials and bucket.
         #
         # @param config [Configuration] application configuration
         # @param logger [#debug, nil] logger used for diagnostics
-        def initialize(config, logger: nil)
+        # @param retry_policy [Retry::Policy, nil] retry settings, defaults to the project policy
+        # @param sleeper [#call, nil] waiting strategy used between attempts
+        def initialize(config, logger: nil, retry_policy: nil, sleeper: nil)
             @bucket = config.bucket
             @logger = logger || R2::Logging::NullLogger.new
+            @retry_policy = retry_policy || Retry::Policy.new
+            @sleeper = sleeper
             @s3 = Aws::S3::Client.new(
                 region: config.region,
                 access_key_id: config.access_key_id,
@@ -31,16 +43,29 @@ module R2
         # Receives content already prepared by the layer that uses the storage
         # and delivers it to Cloudflare R2.
         #
+        # The content type is determined from the object key, unless an
+        # explicit value is given, so the stored object is served with the
+        # correct type instead of the generic binary type.
+        #
+        # When the content comes from a stream, it is rewound before every
+        # attempt, since a retry must read the content from the beginning.
+        #
         # @param key [String] object key in the bucket
         # @param body [IO, String] content of the object to upload
+        # @param content_type [String, nil] content type stored in the object metadata
         # @raise [Errors::Error] if the operation fails
-        def upload(key:, body:)
-            @logger.debug("Uploading object #{key.inspect} to bucket #{@bucket.inspect}.")
-            @s3.put_object(
-                bucket: @bucket,
-                key: key,
-                body: body
-            )
+        def upload(key:, body:, content_type: nil)
+            type = content_type || ContentType.for(key)
+            @logger.debug("Uploading object #{key.inspect} as #{type.inspect} to bucket #{@bucket.inspect}.")
+            with_retries(operation: "upload", key: key) do
+                body.rewind if body.respond_to?(:rewind)
+                @s3.put_object(
+                    bucket: @bucket,
+                    key: key,
+                    body: body,
+                    content_type: type
+                )
+            end
             @logger.debug("Upload of object #{key.inspect} completed.")
             nil
         rescue StandardError => e
@@ -56,10 +81,12 @@ module R2
         # @raise [Errors::Error] if the operation fails
         def delete(key:)
             @logger.debug("Deleting object #{key.inspect} from bucket #{@bucket.inspect}.")
-            @s3.delete_object(
-                bucket: @bucket,
-                key: key
-            )
+            with_retries(operation: "delete", key: key) do
+                @s3.delete_object(
+                    bucket: @bucket,
+                    key: key
+                )
+            end
             @logger.debug("Deletion of object #{key.inspect} completed.")
             nil
         rescue StandardError => e
@@ -68,12 +95,24 @@ module R2
 
         # Lists the objects stored in the configured bucket.
         #
+        # Every page of the listing is requested, so all the stored objects
+        # are returned regardless of the amount of keys in the bucket.
+        #
+        # @param prefix [String, nil] lists only the objects whose keys start with the prefix
         # @return [Array<String>] keys of the stored objects
         # @raise [Errors::Error] if the operation fails
-        def list
-            @logger.debug("Listing objects in bucket #{@bucket.inspect}.")
-            response = @s3.list_objects_v2(bucket: @bucket)
-            keys = response.contents.map(&:key)
+        def list(prefix: nil)
+            @logger.debug("Listing objects in bucket #{@bucket.inspect} with prefix #{prefix.inspect}.")
+            keys = []
+            token = nil
+
+            loop do
+                response = list_page(token, prefix)
+                keys.concat(response.contents.map(&:key))
+                token = response.next_continuation_token
+                break if token.nil? || token.empty?
+            end
+
             @logger.debug("Found #{keys.size} object(s) in bucket #{@bucket.inspect}.")
             keys
         rescue StandardError => e
@@ -83,7 +122,9 @@ module R2
         # Downloads an object from the configured bucket.
         #
         # The content is streamed directly to the destination file, so large
-        # objects do not need to be fully loaded into memory.
+        # objects do not need to be fully loaded into memory. Every attempt
+        # writes the file from the beginning, avoiding a partially written
+        # content when a retry is needed.
         #
         # @param key [String] object key in the bucket
         # @param destination [String] local path where the content is written
@@ -91,8 +132,10 @@ module R2
         # @raise [Errors::Error] if the operation fails
         def download(key:, destination:)
             @logger.debug("Downloading object #{key.inspect} to #{destination.inspect}.")
-            File.open(destination, "wb") do |file|
-                @s3.get_object(bucket: @bucket, key: key, response_target: file)
+            with_retries(operation: "download", key: key) do
+                File.open(destination, "wb") do |file|
+                    @s3.get_object(bucket: @bucket, key: key, response_target: file)
+                end
             end
             @logger.debug("Download of object #{key.inspect} completed.")
             destination
@@ -100,8 +143,71 @@ module R2
             raise_storage_error(e, operation: "download", key: key, destination: destination)
         end
 
+        # Checks whether an object exists in the configured bucket.
+        #
+        # The object metadata is requested instead of the content, so the
+        # check is cheap regardless of the object size.
+        #
+        # @param key [String] object key in the bucket
+        # @return [Boolean] true when the object exists
+        # @raise [Errors::Error] if the operation fails
+        def exists?(key:)
+            @logger.debug("Checking whether object #{key.inspect} exists in bucket #{@bucket.inspect}.")
+            with_retries(operation: "exists", key: key) do
+                @s3.head_object(bucket: @bucket, key: key)
+            end
+            @logger.debug("Object #{key.inspect} was found in bucket #{@bucket.inspect}.")
+            true
+        rescue Aws::S3::Errors::NoSuchKey, Aws::S3::Errors::NotFound
+            @logger.debug("Object #{key.inspect} was not found in bucket #{@bucket.inspect}.")
+            false
+        rescue StandardError => e
+            raise_storage_error(e, operation: "exists", key: key)
+        end
+
         private
 
+        # Requests a single page of the object listing.
+        #
+        # @param token [String, nil] continuation token of the page
+        # @param prefix [String, nil] lists only the objects whose keys start with the prefix
+        # @return [Object] response of the listing operation
+        def list_page(token, prefix)
+            params = { bucket: @bucket }
+            params[:prefix] = prefix unless prefix.nil?
+            params[:continuation_token] = token unless token.nil?
+
+            with_retries(operation: "list") { @s3.list_objects_v2(**params) }
+        end
+
+        # Runs the given block retrying transient network failures.
+        #
+        # @param operation [String] operation being performed
+        # @param key [String, nil] object key involved in the operation
+        # @yield the request to run against the storage
+        # @return [Object] result of the block
+        def with_retries(operation:, key: nil, &)
+            R2::Retry.call(
+                policy: @retry_policy,
+                retry_on: RETRYABLE_ERRORS,
+                logger: @logger,
+                sleeper: @sleeper,
+                description: describe_operation(operation, key),
+                &
+            )
+        end
+
+        # Builds the description of an operation used in the diagnostics.
+        #
+        # @param operation [String] operation being performed
+        # @param key [String, nil] object key involved in the operation
+        # @return [String] operation description
+        def describe_operation(operation, key)
+            return "#{operation} on bucket #{@bucket}" if key.nil?
+
+            "#{operation} of #{key}"
+        end
+
         # Converts storage layer errors into project domain errors, avoiding
         # exposing internal details of the implementations.
         #

data/lib/r2/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module R2
-    VERSION = "1.1.0"
+    VERSION = "1.2.0"
 end

data/lib/r2.rb

@@ -2,7 +2,9 @@
 
 require "r2/cli"
 require "r2/configuration"
+require "r2/content_type"
 require "r2/errors"
 require "r2/logging"
+require "r2/retry"
 require "r2/storage"
 require "r2/version"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cloudflare-r2-cli
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - rpzerosixcode
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-09 00:00:00.000000000 Z
+date: 2026-09-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-s3
@@ -127,8 +127,10 @@ files:
 - lib/r2.rb
 - lib/r2/cli.rb
 - lib/r2/configuration.rb
+- lib/r2/content_type.rb
 - lib/r2/errors.rb
 - lib/r2/logging.rb
+- lib/r2/retry.rb
 - lib/r2/storage.rb
 - lib/r2/version.rb
 homepage: https://github.com/rpzerosixcode/cloudflare-r2-cli