gem-hunter

rc - Rust S3 CLI Client

Features

Installation

Binary Download

DEB/RPM Packages

Homebrew (macOS/Linux)

brew install rustfs/tap/rc

Scoop (Windows)

scoop bucket add rustfs https://github.com/rustfs/scoop-bucket
scoop install rustfs/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 the local filesystem and RustFS
rc mirror ./local-dir/ local/bucket/backup/

# 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 local/bucket/file.txt --expire 24h

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

rc cp ./january.csv ./february.csv local/reports/ --concurrency 8 --summary
rc cp -r ./reports/ local/archive/ --include '*.csv' --exclude 'private-*' --newer-than 7d
rc cp -r ./reports/ local/archive/ --rate-limit 10MiB/s --retry-attempts 5 --continue-on-error

rc get local/reports/report.json ./report.json
rc put ./report.json local/reports/

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 policy.json

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

# Detach multiple policies from a user
rc admin policy detach local/ readonly diagnostics --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 a policy file
rc admin service-account create local/ SAKEY123 SASECRET123 --policy ./service-account-policy.json

# Create a service account with inline policy JSON
rc admin service-account create local/ SAKEY123 SASECRET123 --policy-json '{"Version":"2012-10-17","Statement":[]}'

# Update selected fields on an existing service account
rc admin service-account update local/ SAKEY123 --policy ./service-account-policy.json --description "Automation access"

# Inspect any access key and resolve whether it belongs to a user, service account, or STS credential
rc admin access-key info local/ AKIAIOSFODNN7EXAMPLE
rc admin access-key info local/ AKIAIOSFODNN7EXAMPLE --json

# On-demand migration: serve misses from an external source bucket and backfill the rest
RC_ODM_SECRET_KEY=... rc admin bucket migration set local/photos --provider minio \
  --endpoint https://source.example.com:9000 --region us-east-1 \
  --source-bucket legacy-photos --access-key AKIASOURCE --dry-run
rc admin bucket migration status local/photos
rc admin bucket migration backfill start local/photos
rc admin bucket migration backfill status local/photos --watch

# 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

# Manage bucket CORS configuration
rc bucket cors list local/my-bucket
rc bucket cors get local/my-bucket
rc bucket cors set local/my-bucket cors.xml
cat cors.xml | rc bucket cors set local/my-bucket -
rc bucket cors set local/my-bucket --file cors.json
rc cors remove local/my-bucket

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

# Expire noncurrent versions after 1 day and clean up the remaining delete marker
rc ilm rule add local/my-bucket --noncurrent-expiry-days 1 --expired-object-delete-marker

# 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

# Allow self-signed or otherwise untrusted target certificates for this
# replication target only.
rc replicate add local/my-bucket \
  --remote-bucket remote/target-bucket \
  --replicate delete,delete-marker,existing-objects \
  --insecure

# Upload a local PEM CA bundle so RustFS can trust a private CA when it
# connects to the remote replication target.
rc replicate add local/my-bucket \
  --remote-bucket remote/target-bucket \
  --replicate delete,delete-marker,existing-objects \
  --ca-cert ./private-ca.pem

# 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

# Aggregate background heal status
rc admin heal status local

# Root recursive manual heal
rc admin heal start local --scan-mode deep
rc admin heal status local --client-token <TOKEN_FROM_START>
rc admin heal stop local --client-token <TOKEN_FROM_START>

# Bucket manual heal
rc admin heal start local --bucket mybucket --scan-mode deep
rc admin heal status local --bucket mybucket --client-token <TOKEN_FROM_START>
rc admin heal stop local --bucket mybucket --client-token <TOKEN_FROM_START>

# Global force stop
rc admin heal stop local

# Pool expansion and decommission workflows
rc admin pool list local
rc admin pool status local 1 --by-id
rc admin expand start local
rc admin expand status local
rc admin expand stop local
rc admin decommission start local '/data/pool1/disk{1...4}'
rc admin decommission status local '/data/pool1/disk{1...4}'
rc admin decommission cancel local 1 --by-id
rc admin decommission clear local 1 --by-id

# Rebalance data after adding server pools
rc admin rebalance start local
rc admin rebalance status local
rc admin rebalance stop local

# Site replication across clusters (peer sites given as alias names)
rc admin replicate add site1 site2
rc admin replicate info site1
rc admin replicate status site1
rc admin replicate remove site1 --all

# Service control (restart/stop perform a graceful shutdown;
# a process manager such as systemd relaunches after restart)
rc admin service restart local
rc admin service stop local

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

Operational Health and Usage

# Public liveness and dependency-readiness probes
rc ping local
rc ready local --timeout 2

# Prefer the RustFS background-scanner snapshot
rc du local

# Explicitly permit a portable paginated S3 fallback
rc du local/photos/2026/ --fallback --versions
rc du local/photos --fallback --incomplete

Command Overview

Admin Subcommands

ILM Subcommands

Replicate 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

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

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

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

License

Acknowledgments