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/

# Mirror between S3 locations
rc mirror local/bucket1/ local/bucket2/

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

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

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

Admin Operations (IAM)

# List users
rc admin user list local/

# Add a new user
rc admin user add local/ newuser secretpassword

# Create a policy
rc admin policy create local/ readonly --file policy.json

# Attach policy to user
rc admin policy attach local/ readonly --user newuser

# Create a service account
rc admin service-account add local/ myuser

Admin Operations (Cluster)

# Cluster information
rc admin info cluster local
rc admin info server local
rc admin info disk local --offline

# Heal operations
rc admin heal status local
rc admin heal start local --bucket mybucket --scan-mode deep
rc admin heal start local --dry-run
rc admin heal stop local

# JSON output
rc admin info cluster local --json
rc admin heal status local --json

Command Overview

Admin Subcommands

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

Compatibility

Supported Backends

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