S3 CLI Tools

Connect S3 CLI tools like awscli, s3cmd, rclone, and more to Garage

Garage is compatible with a wide range of S3 CLI tools, making it easy to manage your object storage through the command line. These tools are particularly suitable for debugging, backups, website deployments, or any scripted task that needs to handle data.

Recommended Tools

The following tools are tested and work reliably with Garage:

Tool	Status	Notes
AWS CLI	✅	Recommended, native S3 support
Minio Client	✅	Recommended, user-friendly
rclone	✅	Excellent for sync operations
s3cmd	✅	Classic S3 tool
s5cmd	✅	High-performance tool
Cyberduck/duck	✅	GUI and CLI options
WinSCP	✅	Windows support
sftpgo	✅	SFTP gateway to S3

AWS CLI

The AWS CLI is one of the most widely used tools for interacting with S3-compatible storage.

Configuration

Create a credentials file at ~/.aws/credentials:

[default]
aws_access_key_id=GKxxxx
aws_secret_access_key=xxxx

Then create a config file at ~/.aws/config:

[default]
region=garage
endpoint_url=http://127.0.0.1:3900

If you’re using awscli version <1.29.0 or <2.13.0, you need to pass --endpoint-url to each CLI invocation explicitly. See the workaround below.

Workaround for Older Versions

For older AWS CLI versions, add this to your ~/.bashrc:

function aws { command aws --endpoint-url http://127.0.0.1:3900 $@ ; }

Don’t forget to run source ~/.bashrc or start a new terminal.

Common Operations

List Buckets

aws s3 ls

List Objects

aws s3 ls s3://my-bucket

Upload File

aws s3 cp /path/to/file.txt s3://my-bucket/

Download File

aws s3 cp s3://my-bucket/file.txt /tmp/

Sync Directory

aws s3 sync ./local-dir s3://my-bucket/remote-dir

Minio Client

The Minio client (mc) provides a modern, user-friendly interface for S3 operations.

On some Linux distributions like Arch Linux, the Minio client is called mcli to avoid conflicts with Midnight Commander.

Setup

Define a new S3 server alias:

mc alias set \
  garage \
  http://127.0.0.1:3900 \
  GKxxxx \
  your-secret-key \
  --api S3v4

Common Operations

List Buckets

mc ls garage/

List Objects

mc ls garage/my-bucket

Upload File

mc cp /proc/cpuinfo garage/my-bucket/cpuinfo.txt

Download File

mc cp garage/my-bucket/cpuinfo.txt /tmp/

Mirror Directory

mc mirror --overwrite ./local-dir garage/my-bucket

rclone

rclone is excellent for synchronizing files between different storage systems.

Configuration

You can configure rclone interactively:

rclone config

Or create a configuration file directly at ~/.config/rclone/rclone.conf:

[garage]
type = s3
provider = Other
env_auth = false
access_key_id = GKxxxx
secret_access_key = your-secret-key
region = garage
endpoint = http://127.0.0.1:3900
force_path_style = true
acl = private
bucket_acl = private

Common Operations

List Buckets

rclone lsd garage:

List Objects

rclone lsd garage:my-bucket

Copy File

echo "hello world" > /tmp/hello.txt
rclone copy /tmp/hello.txt garage:my-bucket/

Sync Directory

rclone sync ./local-dir garage:my-bucket/remote-dir

Performance Tips

Use the --fast-list option when accessing buckets with large amounts of objects. This will tremendously accelerate operations like rclone sync or rclone ncdu by reducing the number of ListObjects calls.

Cloudflare Proxy Compatibility

If you’re running Garage behind a Cloudflare proxy and see AccessDenied: Forbidden: Invalid signature errors, add this flag:

rclone lsd --s3-sign-accept-encoding=false garage:

s3cmd

s3cmd is a classic command-line tool for S3 operations.

Configuration

Create a configuration file at ~/.s3cfg or s3cmd.cfg:

[default]
access_key = GKxxxx
secret_key = your-secret-key
host_base = 127.0.0.1:3900
host_bucket = 127.0.0.1:3900
use_https = False

Common Operations

List Buckets

s3cmd ls

List Objects

s3cmd ls s3://my-bucket

Upload File

echo "hello world" > /tmp/hello.txt
s3cmd put /tmp/hello.txt s3://my-bucket/

Download File

s3cmd get s3://my-bucket/hello.txt hello.txt

s5cmd

s5cmd is a high-performance S3 tool with parallel operations support.

Configuration

Set up environment variables:

export AWS_ACCESS_KEY_ID=GKxxxx
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_DEFAULT_REGION=garage
export AWS_ENDPOINT=http://localhost:3900

Usage

s5cmd --endpoint-url=$AWS_ENDPOINT ls

See the s5cmd documentation for more commands.

Cyberduck & duck

Cyberduck provides both a GUI application and a CLI tool called duck.

GUI Setup

Within Cyberduck, a Garage connection profile is available in Preferences → Profiles. Enable this profile to configure connections to Garage.

CLI Setup

Create the folder hierarchy:

mkdir -p ~/.duck/profiles/

Download the Garage connection profile and save it to ~/.duck/profiles/garage.cyberduckprofile.

Set your credentials in ~/.duck/credentials:

export AWS_ACCESS_KEY_ID="GKxxxx"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export HOST="s3.garage.localhost"
export PORT="3900"
export PROTOCOL="http"

cat > ~/.duck/credentials <<EOF
$PROTOCOL\://$AWS_ACCESS_KEY_ID@$HOST\:$PORT=$AWS_SECRET_ACCESS_KEY
EOF

Optionally, add a wrapper to your ~/.bashrc:

function duck { command duck --username GKxxxx $@ ; }

Common Operations

List Buckets

duck --list garage:/

List Objects

duck --list garage:/my-bucket/

Download File

duck --download garage:/my-bucket/file.txt /tmp/

Upload File

duck --upload /tmp/file.txt garage:/my-bucket/

Delete File

duck --delete garage:/my-bucket/file.txt

WinSCP

WinSCP provides both GUI and CLI interfaces for Windows users.

CLI Usage

open s3://GKxxxxx:secret-key@127.0.0.1:3900 -certificate=* -rawsettings S3DefaultRegion=garage S3UrlStyle=1
ls
ls my-bucket/
get my-bucket/file.txt C:\\tmp\\file.txt
put C:\\tmp\\file.txt my-bucket/another-file.txt
rm my-bucket/file.txt
exit

• WinSCP only supports TLS connections for S3
• Use -certificate=* to allow self-signed certificates

sftpgo

sftpgo provides an SFTP gateway to S3 storage, allowing you to access Garage through SFTP clients.

Setup

Initialize the database:

sftpgo initprovider

Start the daemon (listens on :8080 for HTTP and :2022 for SSH by default):

sftpgo serve

Configuration

1. Go to the admin web interface at http://localhost:8080/web/admin/
2. Create the required admin account
3. Create a user account with these filesystem settings:
   • Storage: AWS S3 (Compatible)
   • Bucket: your bucket name
   • Region: garage (or your configured region)
   • Access key: your access key
   • Access secret: your secret key
   • Endpoint: your endpoint (e.g., https://garage.example.com)
   • Tick “Use path-style addressing”

Access via SFTP

sftp -P2022 username@localhost
ls

You can also access files through the web interface at http://localhost:8080/web/client.

Next Steps

Application Integrations

Connect Nextcloud, Mastodon, Peertube, and more

Static Website Hosting

Deploy Hugo, Jekyll, and other static sites