rc - Rust S3 CLI Client

A S3-compatible command-line client written in Rust.

Features

• 🚀 High Performance - Written in Rust with async concurrent operations
• 🔧 S3 Compatible - Supports RustFS, MinIO, AWS S3, and other S3-compatible services
• 📦 Cross-Platform - Supports Linux, macOS, and Windows
• 🎨 Friendly Output - Human-readable and JSON format output
• 🔒 Secure - Secure credential storage, no sensitive data in logs

Installation

Binary Download

Download the appropriate binary for your platform from the Releases page.

Homebrew (macOS/Linux)

brew install rustfs/tap/rc

Cargo

cargo install rustfs-cli

Build from Source

git clone https://github.com/rustfs/cli.git
cd cli
cargo build --release

Quick Start

Configure Aliases

# Add local S3 service
rc alias set local http://localhost:9000 accesskey secretkey

# Add AWS S3
rc alias set s3 https://s3.amazonaws.com AKIAIOSFODNN7EXAMPLE wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# List all aliases
rc alias list

Basic Operations

# List buckets
rc ls local/

# Create bucket
rc mb local/my-bucket

# Upload file
rc cp ./file.txt local/my-bucket/

# Download file
rc cp local/my-bucket/file.txt ./

# View object info
rc stat local/my-bucket/file.txt

# Delete object
rc rm local/my-bucket/file.txt

# Delete bucket
rc rb local/my-bucket

Advanced Operations

# Recursively copy directory
rc cp -r ./local-dir/ local/bucket/remote-dir/

# Sync directories
rc mirror ./local-dir local/bucket/remote-dir

# Find objects
rc find local/bucket --name "*.txt" --newer-than 1d

# Generate download link
rc share download local/bucket/file.txt --expire 24h

# View directory tree
rc tree local/bucket -L 3

Command Overview

Command	Description
alias	Manage storage service aliases
ls	List buckets or objects
mb	Make bucket
rb	Remove bucket
cp	Copy objects
mv	Move objects
rm	Remove objects
cat	Display object contents
head	Display object header
stat	Display object metadata
find	Find objects
diff	Compare two locations
mirror	Mirror sync
tree	Tree view display
share	Generate share links
pipe	Upload from stdin
completions	Generate shell completion scripts

Optional Commands (requires backend support)

Command	Description
version	Manage bucket versioning
tag	Manage object tags

Output Format

Human-Readable (default)

rc ls local/bucket
[2024-01-15 10:30:00]     0B dir/
[2024-01-15 10:30:00] 1.2MiB file.txt

JSON Format

rc ls local/bucket --json

{
  "items": [
    {"key": "dir/", "is_dir": true},
    {"key": "file.txt", "size_bytes": 1258291, "size_human": "1.2 MiB", "is_dir": false}
  ],
  "truncated": false
}

Shell Completion

Generate and install shell completion scripts:

Bash

rc completions bash > ~/.bash_completion.d/rc
# Or add to .bashrc:
# source <(rc completions bash)

Zsh

rc completions zsh > ~/.zfunc/_rc
# Ensure ~/.zfunc is in your fpath (add to .zshrc):
# fpath=(~/.zfunc $fpath)
# autoload -Uz compinit && compinit

Fish

rc completions fish > ~/.config/fish/completions/rc.fish

PowerShell

rc completions powershell >> $PROFILE

Configuration

Configuration file is located at ~/.config/rc/config.toml:

schema_version = 1

[defaults]
output = "human"
color = "auto"
progress = true

[[aliases]]
name = "local"
endpoint = "http://localhost:9000"
access_key = "accesskey"
secret_key = "secretkey"
region = "us-east-1"

Exit Codes

Code	Description
0	Success
1	General error
2	Usage/path error
3	Network error (retryable)
4	Authentication/permission error
5	Resource not found
6	Conflict/precondition failed
7	Feature not supported
130	Interrupted (Ctrl+C)

Compatibility

Supported Backends

Backend	Tier	Description
RustFS	Tier 1	Fully supported
MinIO	Tier 2	Fully supported
AWS S3	Tier 3	Best effort support
Other S3-compatible	Best Effort	No guarantee

Minimum Rust Version

• Rust 1.92 or higher (Edition 2024)

Development

Build

cargo build --workspace

Test

# Unit tests
cargo test --workspace

# Integration tests (requires S3-compatible backend)
docker compose -f docker/docker-compose.yml up -d
cargo test --workspace --features integration
docker compose -f docker/docker-compose.yml down

Lint

cargo fmt --all --check
cargo clippy --workspace -- -D warnings

Contributing

Contributions are welcome! Please read AGENTS.md for development guidelines.

License

This project is dual-licensed under MIT or Apache-2.0. See LICENSE-MIT and LICENSE-APACHE.

Acknowledgments

• MinIO Client (mc) - Inspiration for CLI design
• aws-sdk-s3 - AWS S3 SDK for Rust