cloudflare-r2-cli 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ceadf052d3952605f7b5c2d6adf2bb1baae97a8bcb00683713434916a7dc068
+  data.tar.gz: 9e53105d7191fa1385f20eae36e936da2c3f1bb0700204c32b65591424ef0fd8
+SHA512:
+  metadata.gz: bfcd9ae92ac95ae4184f55099d0d324c40cc41d86698f6fd238aca320e436df6d22b71c3f21a8748a985fc2be14335b618493bbec1fd67c886442492b7efecd9
+  data.tar.gz: f39eeffa35d7b63bf58cb7010654c17c5154d28f1fa31069f6b13274c2ca8a9ac2469b368191b9c7fc1b3995e7e8076d279e56d011cf022f40256d7870896348

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+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.0.0] - 2026-08-30
+
+First stable release of `cloudflare-r2-cli`.
+
+### Added
+
+* Initial release with the essential commands to manage objects on Cloudflare R2:
+  * `r2 upload` — uploads a file to the configured bucket.
+  * `r2 delete` — deletes a file from the configured bucket.
+  * `r2 list` — lists the files stored in the configured bucket.
+* Configuration through environment variables (`R2_ACCESS_KEY_ID`,
+  `R2_SECRET_ACCESS_KEY`, `R2_ENDPOINT`, `R2_REGION` and `R2_BUCKET`).
+* Clear error messages and non-zero exit codes on failures.
+* Unit, integration and E2E test suites.
+* Continuous integration via GitHub Actions.
+
+[Unreleased]: https://github.com/rpzerosixcode/cloudflare-r2-cli/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/rpzerosixcode/cloudflare-r2-cli/releases/tag/v1.0.0

data/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rpzerosixcode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,117 @@
+# Cloudflare R2 CLI
+
+Ruby CLI to manage objects on Cloudflare R2 from the terminal.
+
+## Requirements
+
+* Ruby **3.3** or higher.
+
+## Installation
+
+### From a published gem
+
+```console
+$ gem install cloudflare-r2-cli
+```
+
+### From the source code
+
+```console
+$ 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.0.0.gem
+```
+
+## Usage
+
+### Configuration
+
+Before using the CLI, define the required environment variables:
+
+| Variable               | Description                                        |
+| ---------------------- | -------------------------------------------------- |
+| `R2_ACCESS_KEY_ID`     | Cloudflare R2 S3 access key ID.                    |
+| `R2_SECRET_ACCESS_KEY` | Cloudflare R2 S3 secret access key.                |
+| `R2_ENDPOINT`          | Cloudflare R2 S3-compatible endpoint.              |
+| `R2_REGION`            | Region of the S3-compatible endpoint. *(optional, default `auto`)* |
+| `R2_BUCKET`            | Default bucket used by the CLI.                    |
+
+A fillable template is available in [`.env.example`](.env.example).
+
+Credentials are read only from environment variables and must never be
+inserted into code or versioned files. See
+[`docs/SECURITY.md`](docs/SECURITY.md) for more details.
+
+### Upload
+
+Uploads an image to the configured bucket:
+
+```console
+$ r2 upload image.jpg
+$ r2 upload ./images/photo.png
+```
+
+The object key in the bucket will be the name of the given file. On success,
+a confirmation message is displayed.
+
+### Delete
+
+Deletes a file stored in the configured bucket:
+
+```console
+$ r2 delete image.jpg
+```
+
+The operation is confirmed by the result of the deletion returned by the service.
+
+### List
+
+Lists the files stored in the configured bucket:
+
+```console
+$ r2 list
+```
+
+On any error, the CLI displays the corresponding message on the error output
+and exits with status code `1`.
+
+## Development
+
+The development guidelines, branches and commits are described in
+[`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md).
+
+### Tests
+
+Run the full suite (unit, integration and E2E):
+
+```console
+$ bundle exec rake
+```
+
+Run only one level:
+
+```console
+$ bundle exec rake unit
+$ bundle exec rake integration
+$ bundle exec rake e2e
+```
+
+The E2E tests require real Cloudflare R2 credentials, provided by the `.env`
+file or by the environment. Without them, the scenarios are marked as
+pending and do not fail.
+
+## Documentation
+
+* [Architecture](docs/ARCHITECTURE.md) — Overview of the project architecture.
+* [Changelog](CHANGELOG.md) — Version history of the project.
+* [Decisions](docs/DECISIONS.md) — Architecture and project decisions.
+* [Features](docs/FEATURES.md) — Planned and implemented features.
+* [Roadmap](docs/ROADMAP.md) — Planned evolution of the project.
+* [Security](docs/SECURITY.md) — General security guidelines of the project.
+* [Development](docs/DEVELOPMENT.md) — Development guidelines of the project.
+
+## License
+
+[MIT License](./LICENCE) — Terms of use and distribution of the project.

data/Rakefile

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rubocop/rake_task"
+require "rspec/core/rake_task"
+require_relative "lib/r2/version"
+
+RuboCop::RakeTask.new
+
+desc "Runs all tests"
+RSpec::Core::RakeTask.new(:spec)
+
+desc "Runs the unit tests"
+RSpec::Core::RakeTask.new(:unit) do |task|
+    task.pattern = "spec/unit/**/*_spec.rb"
+end
+
+desc "Runs the integration tests"
+RSpec::Core::RakeTask.new(:integration) do |task|
+    task.pattern = "spec/integration/**/*_spec.rb"
+end
+
+desc "Runs the E2E tests"
+RSpec::Core::RakeTask.new(:e2e) do |task|
+    task.pattern = "spec/e2e/**/*_spec.rb"
+end
+
+desc "Builds the gem into pkg/"
+task :build do
+    FileUtils.mkdir_p("pkg")
+    gem_file = "pkg/cloudflare-r2-cli-#{R2::VERSION}.gem"
+    sh "gem build r2.gemspec --output #{gem_file}"
+end
+
+desc "Installs the gem locally"
+task install: :build do
+    gem_file = "pkg/cloudflare-r2-cli-#{R2::VERSION}.gem"
+    sh "gem install #{gem_file} --no-document"
+end
+
+desc "Runs the CI checks (style, tests and packaging)"
+task ci: %i[rubocop spec build]
+
+task default: :spec

data/bin/r2

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+require "r2"
+
+R2::CLI.start(ARGV)

data/docs/ARCHITECTURE.md

@@ -0,0 +1,92 @@
+# Architecture
+
+## Test Strategy
+
+* [Testing](architecture/testing.md) — Test strategy and organization.
+
+## Documentation
+
+### Architecture
+
+* [CLI](architecture/cli.md) — Structure and operation of the command line interface.
+* [Configuration](architecture/configuration.md) — Organization and management of the application settings.
+* [Errors](architecture/errors.md) — Strategy and organization of error handling.
+* [Storage](architecture/storage.md) — Organization of the storage and persistence layer.
+* [Testing](architecture/testing.md) — Test strategy and organization.
+
+## Project Structure
+
+```text
+C:.
+|   CHANGELOG.md
+|   LICENCE
+|   README.md
+|   Rakefile
+|   r2.gemspec
+|   Gemfile
+|   Gemfile.lock
+|   .env.example
+|   .gitattributes
+|   .gitignore
+|   .rspec
+|   .rubocop.yml
+|
++---.github
+|   \---workflows
+|           ci.yml
+|           release.yml
+|
++---bin
+|       r2
+|
++---docs
+|   |   ARCHITECTURE.md
+|   |   DECISIONS.md
+|   |   DEVELOPMENT.md
+|   |   FEATURES.md
+|   |   ROADMAP.md
+|   |   SECURITY.md
+|   |
+|   \---architecture
+|           cli.md
+|           configuration.md
+|           errors.md
+|           storage.md
+|           testing.md
+|
++---lib
+|   |   r2.rb
+|   |
+|   \---r2
+|           cli.rb
+|           configuration.rb
+|           errors.rb
+|           storage.rb
+|           version.rb
+|
+\---spec
+    |   spec_helper.rb
+    |
+    +---e2e
+    |       e2e_spec.rb
+    |
+    +---integration
+    |       cli_storage_spec.rb
+    |
+    +---support
+    |       cleanup.rb
+    |       cli_expectations.rb
+    |       cli_runner.rb
+    |       e2e_helper.rb
+    |       env_helper.rb
+    |       fake_s3_client.rb
+    |       output_capture.rb
+    |       temp_file_helper.rb
+    |
+    \---unit
+            cli_spec.rb
+            configuration_spec.rb
+            errors_spec.rb
+            storage_spec.rb
+            version_spec.rb
+```

data/docs/DECISIONS.md

@@ -0,0 +1,30 @@
+# Decisions
+
+This document records the main architectural and project-level decisions.
+
+## Name
+
+The publication name of the project is **`cloudflare-r2-cli`**.
+
+For command usage, **`r2`** is used.
+
+## Content
+
+The project's public content is maintained in **English**.
+
+## Changelog
+
+Formal changelog maintenance starts with version **`1.0.0`** in
+[CHANGELOG.md](../CHANGELOG.md).
+
+## Versioning
+
+The project follows **Semantic Versioning**, starting with version **`1.0.0`**.
+
+## Dependency Injection
+
+Dependencies should preferably be provided through **dependency injection**,
+avoiding unnecessary coupling to concrete implementations.
+
+The project does not use a dependency injection container. Dependencies are
+provided directly by the components that require them.

data/docs/DEVELOPMENT.md

@@ -0,0 +1,65 @@
+# Development
+
+## Branches
+
+The project uses two main branches:
+
+* `develop`: development.
+* `main`: stable version.
+
+## Pull Requests
+
+Changes between branches must be made through Pull Requests.
+
+Pull Requests must be clear, objective and pass the required checks before merging.
+
+## Commits
+
+Commits must follow the **Conventional Commits** convention, using types such as:
+
+* `feat`: new feature.
+* `fix`: bug fix.
+* `docs`: documentation change.
+* `refactor`: refactoring without behavior change.
+* `test`: creation or change of tests.
+* `chore`: maintenance tasks.
+
+## Continuous Integration
+
+The project uses **GitHub Actions** to automatically validate changes on every
+push to the `develop` and `main` branches and on Pull Requests.
+
+The workflow defined in `.github/workflows/ci.yml` runs:
+
+* **Lint** — RuboCop.
+* **Tests** — unit, integration and E2E suites. The E2E scenarios are marked
+  as pending when the test credentials are not configured in the repository
+  secrets (`R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_ENDPOINT`,
+  `R2_REGION` and `R2_TEST_BUCKET`).
+* **Packaging** — gem build (`rake build`).
+
+## Releases
+
+Releases are published from tags in the `v*` format (for example, `v1.0.0`).
+
+The workflow defined in `.github/workflows/release.yml`:
+
+* validates the project (lint, tests and packaging);
+* publishes the gem to RubyGems using the `RUBYGEMS_API_KEY` repository secret;
+* creates a GitHub Release with the packed gem attached.
+
+To release a new version:
+
+1. Update the version in `lib/r2/version.rb` and the changelog in `CHANGELOG.md`.
+2. Merge the changes into `main`.
+3. Create and push the version tag:
+   ```console
+   $ git tag v1.0.0
+   $ git push origin v1.0.0
+   ```
+
+## Principles
+
+Development must prioritize simplicity, organization and code maintenance.
+
+Changes must remain aligned with the current scope of the project and its documentation.

data/docs/FEATURES.md

@@ -0,0 +1,75 @@
+# Features
+
+## Upload
+
+Uploads a file to the configured Cloudflare R2 bucket.
+
+**Usage:**
+
+```console
+$ r2 upload <file>
+```
+
+**Examples:**
+
+```console
+$ r2 upload image.jpg
+$ r2 upload ./images/photo.png
+```
+
+**Behavior:**
+
+* Validates that the given file exists.
+* Validates that the path is not a directory.
+* Opens the file in binary read mode.
+* Uploads the content to the configured Cloudflare R2 bucket.
+* Uses the file name as the object key in the bucket.
+* Displays a success message after the upload.
+
+On error, the corresponding message is displayed and the CLI exits with a non-zero status code.
+
+## Delete
+
+Deletes a file stored in the configured Cloudflare R2 bucket.
+
+**Usage:**
+
+```console
+$ r2 delete <file>
+```
+
+**Example:**
+
+```console
+$ r2 delete image.jpg
+```
+
+**Behavior:**
+
+* Receives the name of the file to delete.
+* 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.
+
+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.
+
+## List
+
+Lists the files stored in the configured Cloudflare R2 bucket.
+
+**Usage:**
+
+```console
+$ r2 list
+```
+
+**Behavior:**
+
+* Queries the objects stored in the configured bucket.
+* 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.

data/docs/ROADMAP.md

@@ -0,0 +1,69 @@
+# Roadmap
+
+The roadmap tracks the planned evolution of the project.
+
+## MVP
+
+The MVP was completed through the phases below.
+
+### Phase 1 — Initial Preparation
+
+Initial structure and fundamental project definitions.
+
+### Phase 2 — Features
+
+Implementation of the essential MVP features.
+
+#### Phase 2.1 — Upload
+
+Implementation of the upload feature.
+
+#### Phase 2.2 — Delete
+
+Implementation of the delete feature.
+
+#### Phase 2.3 — List
+
+Implementation of the list feature.
+
+### Phase 3 — Test Coverage
+
+Implementation and expansion of the project's test coverage.
+
+### Phase 4 — Refinement and Stabilization
+
+Review, refinement and stabilization of the project.
+
+- **Portability** — ensure the CLI works in different environments and operating systems.
+- **Consistency** — review and standardize code, tests, messages and behaviors.
+- **Error handling** — review exception handling and ensure clear, safe messages.
+- **Security** — review settings and ensure sensitive information is not exposed.
+- **Documentation** — review and update the public documentation according to the current state of the project.
+- **Development context** — remove or isolate documentation exclusively related to the development process.
+- **Packaging** — validate the build, installation and execution of the distributed package.
+- **Continuous integration** — integrate the CI flow into the development process, ensuring automated execution of tests and checks.
+- **Final validation** — run the full test suite and validate the project in a clean environment.
+
+### Phase 5 — Release
+
+Preparation and publication of the first stable version of the project.
+
+- **Versioning** — adopt semantic versioning from `1.0.0`.
+- **Changelog** — start formal changelog maintenance from `1.0.0`.
+- **Documentation** — normalize the public documentation according to the stable version.
+- **Development context** — remove or isolate development-specific documentation that is no longer relevant.
+- **MVP context** — remove or update MVP-specific notes and references that no longer apply to the stable version.
+- **Translation** — translate and standardize the project content to English.
+- **Release validation** — validate the version, build and release artifacts before publication.
+- **Publication** — publish the `cloudflare-r2-cli` package on RubyGems.
+- **Post-release validation** — install the published package in a clean environment and confirm it works.
+
+## Future Evolution
+
+Possible next steps for the project:
+
+- **Pagination and control of the number of returned objects** in the `list` command.
+- **Additional configuration sources** such as files and command-line flags.
+- **Multipart uploads** for large files.
+
+> **Note:** The focus will remain a **minimally scalable base** and **essential features**, not optimizations.

data/docs/SECURITY.md

@@ -0,0 +1,19 @@
+# Security
+
+The project follows the following security practices:
+
+- **Credentials through environment variables** — access credentials and
+  sensitive settings are obtained through environment variables and are not
+  stored in source code or versioned files.
+
+- **Isolated test environment** — E2E tests use a dedicated bucket
+  (`R2_TEST_BUCKET`) separated from the default application bucket.
+
+- **Ignored environment files** — `.env` files are excluded from version
+  control. Only the `.env.example` template is versioned.
+
+- **CI and secrets** — CI credentials are provided through repository secrets
+  and are not exposed in workflow logs.
+
+If an access key is accidentally exposed, revoke it immediately through the
+Cloudflare dashboard and generate a new one.

data/docs/architecture/cli.md

@@ -0,0 +1,24 @@
+# CLI
+
+The CLI is responsible for interpreting the user's input, executing the
+corresponding actions and presenting the results.
+
+The `thor` gem is used to define and execute the commands.
+
+## Responsibility
+
+The CLI acts as a **minimal orchestrator**, coordinating the operations at a
+high level.
+
+## Boundaries
+
+The CLI must not implement business rules, directly handle files or know
+details of the implementations and services used.
+
+The execution of the operations must be delegated to the responsible
+components.
+
+## Commands
+
+The available commands and their behaviors are documented in
+[FEATURES.md](../FEATURES.md).

data/docs/architecture/configuration.md

@@ -0,0 +1,24 @@
+# Configuration
+
+The `Configuration` centralizes the application settings.
+
+## Source
+
+The settings are obtained directly from **environment variables**. The other
+components must not access `ENV` directly.
+
+## Variables
+
+The required variables are `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`,
+`R2_ENDPOINT` and `R2_BUCKET`.
+
+The `R2_REGION` variable is optional and, when absent, uses the default value
+`auto`, recommended for Cloudflare R2.
+
+When a required variable is absent, the `Configuration` raises
+`R2::Errors::ConfigurationError` with a message indicating the variable.
+
+## Evolution
+
+The source of the settings may be diversified in the future if a real need
+arises.

data/docs/architecture/errors.md

@@ -0,0 +1,25 @@
+# Errors
+
+Errors are centralized to standardize their handling and keep the application
+behavior consistent.
+
+## Hierarchy
+
+All domain errors inherit from `R2::Errors::Error`:
+
+* `ConfigurationError` — required configuration missing or invalid.
+* `FileNotFoundError` — the given file does not exist.
+* `InvalidFileError` — the given path is not a file.
+* `PermissionError` — no permission to read the given file.
+* `BucketNotFoundError` — the configured bucket does not exist.
+* `NetworkError` — network failure while communicating with Cloudflare R2.
+* `StorageError` — unclassified failure in the storage layer.
+
+## Handling
+
+The specific exceptions of the implementations are converted to the
+`R2::Errors` hierarchy, avoiding exposing internal details of the libraries
+and allowing consumers to catch the generic error or a specific error.
+
+The CLI catches `R2::Errors::Error`, presents the message on the error output
+and exits with a non-zero status code.

data/docs/architecture/storage.md

@@ -0,0 +1,46 @@
+# Storage
+
+The storage abstracts the communication with Cloudflare R2, using the
+`aws-sdk-s3` gem.
+
+## Dependencies
+
+The `aws-sdk-s3` gem requires an XML parser. The project uses `rexml` to meet
+this requirement at runtime.
+
+## Responsibility
+
+The layer is responsible for communicating with Cloudflare R2, receiving the
+data prepared by the upper layers and executing the storage operations.
+
+## Region
+
+The region is provided by the `Configuration` through `R2_REGION`, using `auto`
+as the default.
+
+## Boundaries
+
+The layer must not:
+
+* Read or locate files.
+* Process or transform content.
+* Determine the origin of the content.
+
+These responsibilities belong to the layers that use the storage.
+
+## Configuration
+
+The bucket is defined by the `Storage` configuration and is not informed
+individually in each operation.
+
+Details of the features and their behavior for the user are documented in
+[FEATURES.md](../FEATURES.md).
+
+## Errors
+
+The client failures are converted to the `R2::Errors` hierarchy:
+
+* `Errors::ConfigurationError` — missing or invalid access credentials.
+* `Errors::BucketNotFoundError` — the configured bucket does not exist.
+* `Errors::NetworkError` — network failure in the communication.
+* `Errors::StorageError` — other failures of the storage layer.

data/docs/architecture/testing.md

@@ -0,0 +1,48 @@
+# Testing
+
+Each test type has its own folder, keeping objectives and responsibilities
+separated.
+
+## Unit Tests
+
+Located in `spec/unit/`.
+
+Test components in isolation.
+
+## Integration Tests
+
+Located in `spec/integration/`.
+
+Test the interaction between components.
+
+## E2E Tests
+
+Located in `spec/e2e/`.
+
+Focus on the main flows and expected results, keeping the scenarios simple and
+avoiding tests of internal implementation details.
+
+## Environment
+
+Tests use a dedicated bucket configured through `R2_TEST_BUCKET`.
+
+Temporary files must remain in `tmp/`, which must be included in `.gitignore`.
+
+Resources created by tests must be cleaned up at the end of execution whenever
+possible. E2E tests remove uploaded objects at the end of each scenario.
+
+Credentials can be provided through the `.env` file or the environment.
+
+## Coverage
+
+Tests must cover the main behaviors, including success and error scenarios.
+
+E2E tests are an exception: they must remain extremely simple and focused only
+on the main user flows.
+
+## Execution
+
+Run the full test suite:
+
+```console
+$ bundle exec rake

data/lib/r2/cli.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "errors"
+
+module R2
+    # Command line interface of the project.
+    #
+    # Acts as a minimal orchestrator: interprets the user's input, delegates
+    # the execution to the responsible components and presents the results.
+    class CLI < Thor
+        # Initializes the CLI with its dependencies.
+        #
+        # Dependencies are loaded lazily: they are only created when the first
+        # command actually uses them. This allows help and command listing to
+        # work without a configured environment.
+        #
+        # @param configuration [Configuration] application configuration
+        # @param storage [Storage] storage used in object operations
+        def initialize(
+            *,
+            configuration: nil,
+            storage: nil
+        )
+            super(*)
+            @configuration = configuration
+            @storage = storage
+        end
+
+        # Ensures that Thor exits with a non-zero status code when an
+        # operation fails.
+        def self.exit_on_failure?
+            true
+        end
+
+        # Starts the CLI and clearly presents domain errors not handled by
+        # the commands.
+        #
+        # Errors raised before a command runs (such as missing configuration)
+        # are caught here, shown on the error output and terminate the CLI
+        # with status code 1, avoiding stack traces.
+        def self.start(*args)
+            super
+        rescue Errors::Error => e
+            warn "Error: #{e.message}"
+            exit 1
+        end
+
+        desc "upload FILE", "Uploads an image to R2"
+
+        long_desc <<~LONGDESC
+            Uploads an image to the configured Cloudflare R2 bucket.
+            The object key in the bucket will be the name of the given file.
+
+            Examples:
+
+              $ r2 upload image.jpg
+
+              $ r2 upload ./images/photo.png
+        LONGDESC
+
+        # Uploads an image to the configured Cloudflare R2 bucket.
+        #
+        # The object key in the bucket will be the name of the given file.
+        #
+        # @param file [String] path of the file to upload
+        def upload(file)
+            body = open_file(file)
+            storage.upload(key: File.basename(file), body: body)
+            puts "Image uploaded successfully: #{File.basename(file)}"
+        rescue Errors::Error => e
+            warn "Error: #{e.message}"
+            exit 1
+        ensure
+            body&.close
+        end
+
+        desc "delete FILE", "Deletes a file from R2"
+
+        long_desc <<~LONGDESC
+            Deletes a file from the configured Cloudflare R2 bucket.
+
+            Examples:
+
+              $ r2 delete image.jpg
+        LONGDESC
+
+        # Deletes a file from the configured Cloudflare R2 bucket.
+        #
+        # The operation is considered successful when the storage completes
+        # the request without errors.
+        #
+        # @param file [String] name of the file to delete
+        def delete(file)
+            storage.delete(key: file)
+            puts "File deleted successfully: #{file}"
+        rescue Errors::Error => e
+            warn "Error: #{e.message}"
+            exit 1
+        end
+
+        desc "list", "Lists the files stored in R2"
+
+        long_desc <<~LONGDESC
+            Lists the files stored in the configured Cloudflare R2 bucket.
+
+            Examples:
+
+              $ r2 list
+        LONGDESC
+
+        # Lists the files stored in the configured Cloudflare R2 bucket.
+        def list
+            files = storage.list
+
+            files.each do |file|
+                puts file
+            end
+        rescue Errors::Error => e
+            warn "Error: #{e.message}"
+            exit 1
+        end
+
+        private
+
+        # Opens the given file for reading.
+        #
+        # The file must remain open during the upload, so the block form is
+        # not used; closing is guaranteed in the `ensure` of the `upload`
+        # command.
+        #
+        # @param file [String] file path
+        # @return [File] file opened in binary read mode
+        # @raise [Errors::FileNotFoundError] if the file does not exist
+        # @raise [Errors::InvalidFileError] if the path is not a file
+        # @raise [Errors::PermissionError] if the file cannot be read
+        def open_file(file)
+            raise Errors::FileNotFoundError, "File not found: #{file}" unless File.exist?(file)
+            raise Errors::InvalidFileError, "The provided path is not a file: #{file}" unless File.file?(file)
+            raise Errors::PermissionError, "Permission denied to read the file: #{file}" unless File.readable?(file)
+
+            File.open(file, "rb")
+        rescue Errno::EACCES, Errno::EPERM
+            raise Errors::PermissionError, "Permission denied to read the file: #{file}"
+        end
+
+        # Returns the application configuration, creating it lazily on first use.
+        #
+        # @return [Configuration] application configuration
+        def configuration
+            @configuration ||= Configuration.new
+        end
+
+        # Returns the storage, creating it lazily on first use.
+        #
+        # @return [Storage] storage used in object operations
+        def storage
+            @storage ||= Storage.new(configuration)
+        end
+    end
+end

data/lib/r2/configuration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module R2
+    # Centralized application configuration.
+    #
+    # Settings are read directly from environment variables.
+    class Configuration
+        attr_reader :access_key_id,
+                    :secret_access_key,
+                    :endpoint,
+                    :bucket,
+                    :region
+
+        # Initializes the configuration from environment variables.
+        #
+        # `R2_REGION` is optional and defaults to `auto` when absent, which
+        # is recommended for Cloudflare R2 endpoints.
+        #
+        # @raise [Errors::ConfigurationError] when any required variable
+        #   is not defined
+        def initialize
+            @access_key_id = fetch_required("R2_ACCESS_KEY_ID")
+            @secret_access_key = fetch_required("R2_SECRET_ACCESS_KEY")
+            @endpoint = fetch_required("R2_ENDPOINT")
+            @bucket = fetch_required("R2_BUCKET")
+            @region = ENV.fetch("R2_REGION", "auto")
+        end
+
+        private
+
+        # Gets the value of a required environment variable.
+        #
+        # @param name [String] name of the environment variable
+        # @return [String] variable value
+        # @raise [Errors::ConfigurationError] if the variable is not defined
+        def fetch_required(name)
+            ENV.fetch(name) do
+                raise Errors::ConfigurationError,
+                      "Required environment variable not defined: #{name}"
+            end
+        end
+    end
+end

data/lib/r2/errors.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module R2
+    # Centralization of project errors.
+    module Errors
+        # Base error of the project.
+        #
+        # All domain errors inherit from this class, allowing consumers to
+        # catch the generic error when they do not need to distinguish the
+        # cause, or a specific error when they do.
+        class Error < StandardError
+        end
+
+        # Required configuration missing or invalid.
+        class ConfigurationError < Error
+        end
+
+        # The given file does not exist.
+        class FileNotFoundError < Error
+        end
+
+        # The given path is not a file.
+        class InvalidFileError < Error
+        end
+
+        # No permission to read the given file.
+        class PermissionError < Error
+        end
+
+        # The configured bucket does not exist.
+        class BucketNotFoundError < Error
+        end
+
+        # Network failure while communicating with Cloudflare R2.
+        class NetworkError < Error
+        end
+
+        # Unclassified failure in the storage layer.
+        class StorageError < Error
+        end
+    end
+end

data/lib/r2/storage.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "aws-sdk-s3"
+require_relative "errors"
+
+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.
+    class Storage
+        # Initializes the storage with the configured credentials and bucket.
+        #
+        # @param config [Configuration] application configuration
+        def initialize(config)
+            @bucket = config.bucket
+            @s3 = Aws::S3::Client.new(
+                region: config.region,
+                access_key_id: config.access_key_id,
+                secret_access_key: config.secret_access_key,
+                endpoint: config.endpoint,
+                force_path_style: true
+            )
+        end
+
+        # Uploads an object to the configured bucket.
+        #
+        # Receives content already prepared by the layer that uses the storage
+        # and delivers it to Cloudflare R2.
+        #
+        # @param key [String] object key in the bucket
+        # @param body [IO, String] content of the object to upload
+        # @raise [Errors::Error] if the operation fails
+        def upload(key:, body:)
+            @s3.put_object(
+                bucket: @bucket,
+                key: key,
+                body: body
+            )
+        rescue StandardError => e
+            raise_storage_error(e)
+        end
+
+        # Deletes an object from the configured bucket.
+        #
+        # The operation is considered successful when Cloudflare R2 completes
+        # the request without raising an error.
+        #
+        # @param key [String] object key in the bucket
+        # @raise [Errors::Error] if the operation fails
+        def delete(key:)
+            @s3.delete_object(
+                bucket: @bucket,
+                key: key
+            )
+        rescue StandardError => e
+            raise_storage_error(e)
+        end
+
+        # Lists the objects stored in the configured bucket.
+        #
+        # @return [Array<String>] keys of the stored objects
+        # @raise [Errors::Error] if the operation fails
+        def list
+            response = @s3.list_objects_v2(bucket: @bucket)
+            response.contents.map(&:key)
+        rescue StandardError => e
+            raise_storage_error(e)
+        end
+
+        private
+
+        # Converts storage layer errors into project domain errors, avoiding
+        # exposing internal details of the implementations.
+        #
+        # The original message is preserved when useful.
+        #
+        # @param error [StandardError] original error
+        # @raise [Errors::Error] subclass matching the cause of the error
+        def raise_storage_error(error)
+            case error
+            when Aws::Errors::MissingCredentialsError
+                raise Errors::ConfigurationError,
+                      "Missing or invalid credential environment variables."
+            when Aws::S3::Errors::NoSuchBucket
+                raise Errors::BucketNotFoundError, "Bucket not found: #{@bucket}"
+            when Seahorse::Client::NetworkingError
+                raise Errors::NetworkError, error.message
+            else
+                raise Errors::StorageError, error.message
+            end
+        end
+    end
+end

data/lib/r2/version.rb

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

data/lib/r2.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "r2/cli"
+require "r2/configuration"
+require "r2/errors"
+require "r2/storage"
+require "r2/version"

metadata

@@ -0,0 +1,167 @@
+--- !ruby/object:Gem::Specification
+name: cloudflare-r2-cli
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- rpzerosixcode
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-s3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.229.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.229.0
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.4.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.4.4
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.4'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.90'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.90'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+description: Command line tool in Ruby to manage objects on Cloudflare R2 directly
+  from the terminal.
+email:
+executables:
+- r2
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENCE
+- README.md
+- Rakefile
+- bin/r2
+- docs/ARCHITECTURE.md
+- docs/DECISIONS.md
+- docs/DEVELOPMENT.md
+- docs/FEATURES.md
+- docs/ROADMAP.md
+- docs/SECURITY.md
+- docs/architecture/cli.md
+- docs/architecture/configuration.md
+- docs/architecture/errors.md
+- docs/architecture/storage.md
+- docs/architecture/testing.md
+- lib/r2.rb
+- lib/r2/cli.rb
+- lib/r2/configuration.rb
+- lib/r2/errors.rb
+- lib/r2/storage.rb
+- lib/r2/version.rb
+homepage: https://github.com/rpzerosixcode/cloudflare-r2-cli
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rpzerosixcode/cloudflare-r2-cli
+  changelog_uri: https://github.com/rpzerosixcode/cloudflare-r2-cli/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby CLI to manage objects on Cloudflare R2.
+test_files: []