Skip to content

README.md

Latest commit

 

History

History
451 lines (334 loc) · 11.4 KB

README.md

File metadata and controls

451 lines (334 loc) · 11.4 KB

rc - Rust S3 CLI Client

CI License

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. On Linux, use the default linux-amd64 / linux-arm64 artifacts for maximum compatibility (musl static build). If you specifically need glibc-linked builds, use linux-amd64-gnu / linux-arm64-gnu.

Homebrew (macOS/Linux)

brew install rustfs/tap/rc

Cargo

cargo install rustfs-cli

Docker

# Show help
docker run --rm rustfs/rc:latest --help

# Run a command with a local RustFS instance
docker run --rm --network host rustfs/rc:latest \
  alias set local http://localhost:9000 accesskey secretkey

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

# List anonymous access rules
rc anonymous list local/bucket

# Set anonymous access level
rc anonymous set public local/bucket/public

# 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 (access_key + secret_key)
rc admin service-account create local/ AKIAIOSFODNN7EXAMPLE wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# Create a service account with inline policy file
rc admin service-account create local/ SAKEY123 SASECRET123 --policy ./service-account-policy.json

# Manage bucket event notifications
rc event add local/my-bucket arn:aws:sns:us-east-1:123456789012:topic --event 's3:ObjectCreated:*'
rc event list local/my-bucket
rc event remove local/my-bucket arn:aws:sns:us-east-1:123456789012:topic

Lifecycle (ILM) Operations

# Add lifecycle rule: expire objects after 30 days with prefix filter
rc ilm rule add local/my-bucket --expiry-days 30 --prefix "logs/"

# Add lifecycle rule: transition to remote tier after 90 days
rc ilm rule add local/my-bucket --transition-days 90 --storage-class WARM

# List lifecycle rules
rc ilm rule list local/my-bucket

# Edit an existing rule
rc ilm rule edit local/my-bucket --id rule-abc123 --expiry-days 60

# Remove a specific rule or all rules
rc ilm rule remove local/my-bucket --id rule-abc123
rc ilm rule remove local/my-bucket --all

# Export/import lifecycle configuration (JSON)
rc ilm rule export local/my-bucket > lifecycle.json
rc ilm rule import local/my-bucket lifecycle.json

# Manage remote storage tiers
rc ilm tier add rustfs WARM local --endpoint http://remote:9000 --access-key ak --secret-key sk --bucket warm-bucket
rc ilm tier list local
rc ilm tier info WARM local
rc ilm tier remove WARM local --force

# Restore a transitioned (archived) object
rc ilm restore local/my-bucket/archived-file.dat --days 7

Bucket Replication

# Replication requires versioning on both source and destination buckets
rc version enable local/my-bucket
rc version enable remote/target-bucket

# Configure a remote alias with the destination RustFS endpoint URL.
# rc normalizes the remote target endpoint to the host:port form expected by
# the RustFS admin API when creating replication targets.
rc alias set remote http://remote:9000 ACCESS_KEY SECRET_KEY

# Add a replication rule
rc replicate add local/my-bucket \
  --remote-bucket remote/target-bucket \
  --priority 1 \
  --replicate delete,delete-marker,existing-objects

# List replication rules
rc replicate list local/my-bucket

# View replication status/metrics
rc replicate status local/my-bucket

# Update a replication rule
rc replicate update local/my-bucket --id rule-1 --priority 2

# Remove replication rules
rc replicate remove local/my-bucket --id rule-1
rc replicate remove local/my-bucket --all

# Export/import replication configuration (JSON)
rc replicate export local/my-bucket > replication.json
rc replicate import local/my-bucket replication.json

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

Command Description
alias Manage storage service aliases
admin Manage IAM users, policies, groups, service accounts, and cluster operations
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 first N lines of object
stat Display object metadata
find Find objects
anonymous Manage anonymous access to buckets and objects
diff Compare two locations
mirror Mirror sync between S3 locations
tree Tree view display
share Generate presigned URLs
event Manage bucket event notifications
pipe Upload from stdin
version Manage bucket versioning
tag Manage bucket and object tags
quota Manage bucket quota
ilm Manage lifecycle rules, storage tiers, and object restore
replicate Manage bucket replication
completions Generate shell completion scripts

Admin Subcommands

Command Description
admin user Manage IAM users (add, remove, list, info, enable, disable)
admin policy Manage IAM policies (create, remove, list, info, attach)
admin group Manage IAM groups (add, remove, list, info, enable, disable, add-members, rm-members)
admin service-account Manage service accounts (create, remove, list, info)
admin info Display cluster information (cluster, server, disk)
admin heal Manage cluster healing operations (status, start, stop)

ILM Subcommands

Command Description
ilm rule add Add a lifecycle rule to a bucket
ilm rule edit Edit an existing lifecycle rule
ilm rule list List lifecycle rules on a bucket
ilm rule remove Remove lifecycle rules from a bucket
ilm rule export Export lifecycle configuration as JSON
ilm rule import Import lifecycle configuration from JSON
ilm tier add Add a remote storage tier
ilm tier edit Edit tier credentials
ilm tier list List all configured storage tiers
ilm tier info Show details for a specific tier
ilm tier remove Remove a storage tier
ilm restore Restore a transitioned (archived) object

Replicate Subcommands

Command Description
replicate add Add a new replication rule
replicate update Update an existing replication rule
replicate list List replication rules for a bucket
replicate status Show replication status and metrics
replicate remove Remove replication rules
replicate export Export replication configuration as JSON
replicate import Import replication configuration from JSON

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