s3 — a console S3 client

s3 is a command-line utility for performing common S3 operations from your terminal.

It’s a hard fork of s3-cli, inspired by s3cmd, and aims to be a practical drop-in replacement for many everyday workflows.

Features

• Compatible with s3cmd’s config file format
• Supports a subset of s3cmd commands and flags, including:
  • put, get, del, ls, sync, cp
  • smarter path handling for get/put/cp (copy to/from S3, and S3↔S3)
• Faster directory syncs by uploading multiple files in parallel (better bandwidth utilization)
• Multipart uploads for large files, with parallel part uploads (via the SDK’s S3 manager)
• More efficient CPU and local resource usage

Install

Download a binary from the GitHub Releases page.

Configuration

s3 supports both s3cmd-style config files (.s3cfg / ~/.s3cfg) and the standard AWS shared config files (~/.aws/config and ~/.aws/credentials).

.s3cfg / ~/.s3cfg (s3cmd format) and profiles

The .s3cfg / ~/.s3cfg file is an INI file with one or more sections. Credentials and settings are loaded from the selected section (profile). If no profile is specified, s3 uses the [default] section.

Example ~/.s3cfg:

[default]
access_key = foo
secret_key = bar

[profile1]
access_key = foo1
secret_key = bar1

Select a profile via CLI:

s3 --profile profile1 cp file1 s3://bucket/file1
s3 -p profile1 cp file1 s3://bucket/file1

Or via environment variable:

AWS_PROFILE=profile1 s3 cp file1 s3://bucket/file1

Config file resolution order

If you do not pass --config, s3 will try config files in this order:

1. ./.s3cfg (current working directory), if present
2. ~/.s3cfg

To use a different config file path explicitly:

s3 --config /path/to/s3cmd.conf ...

Fallback to ~/.aws shared config

If credentials are not provided via ~/.s3cfg and not provided via environment variables, s3 falls back to the AWS SDK’s standard credential and config resolution (including ~/.aws/config, ~/.aws/credentials, and AWS_PROFILE).

Region

You can override the AWS region used for requests with --region (or AWS_REGION / AWS_DEFAULT_REGION):

s3 --region us-east-1 ls
AWS_REGION=us-east-1 s3 ls

When using a custom --endpoint, the client does not attempt AWS bucket region discovery.

Usage and command reference

In general, command flags and behavior are guided by rsync and common Unix CLI conventions.

Endpoint override

You can override the S3 endpoint used for requests with --endpoint / -e (useful for S3-compatible servers like MinIO):

s3 --endpoint https://custom-s3.example.com cp file1 s3://bucket/file1
s3 -e https://custom-s3.example.com cp file1 s3://bucket/file1

Notes:

• s3 uses path-style bucket addressing for S3 connections.
• If you don’t provide explicit credentials in .s3cfg / ~/.s3cfg (or via --access-key / --secret-key), the AWS SDK credential chain may be used (including ~/.aws/credentials / ~/.aws/config). When talking to a non-AWS endpoint, you typically want credentials that exist on that server.

cp

Copy files to and from S3.

Examples:

s3 cp /path/to/file s3://bucket/key/on/s3
s3 cp s3://bucket/key/on/s3 /path/to/file
s3 cp s3://bucket/key/on/s3 s3://another-bucket/some/thing

get

Download a file from S3 (alias for cp).

put

Upload a file to S3 (alias for cp).

del

Delete an object or a “directory” prefix on S3.

Example:

s3 del [--recursive] s3://bucket/key/on/s3/

rm

Alias for del.

s3 rm [--recursive] s3://bucket/key/on/s3/

sync

Sync between a local directory and S3.

s3 sync [--delete-removed] /path/to/folder/ s3://bucket/key/on/s3/

mv

Move an object already stored in S3.

Example:

s3 mv s3://sourcebucket/source/key s3://destbucket/dest/key

s3cmd compatibility

Implemented

• s3cmd mb s3://BUCKET
• s3cmd rb s3://BUCKET
• s3cmd ls [s3://BUCKET[/PREFIX]]
• s3cmd la
• s3cmd put FILE [FILE...] s3://BUCKET[/PREFIX]
• s3cmd get s3://BUCKET/OBJECT LOCAL_FILE
• s3cmd del s3://BUCKET/OBJECT
• s3cmd rm s3://BUCKET/OBJECT
• s3cmd du [s3://BUCKET[/PREFIX]]
• s3cmd cp s3://BUCKET1/OBJECT1 s3://BUCKET2[/OBJECT2]
• s3cmd modify s3://BUCKET1/OBJECT
• s3cmd sync LOCAL_DIR s3://BUCKET[/PREFIX] or s3cmd sync s3://BUCKET[/PREFIX] LOCAL_DIR
• s3cmd info s3://BUCKET[/OBJECT]

Not yet implemented (for broader compatibility)

• s3cmd restore s3://BUCKET/OBJECT
• s3cmd mv s3://BUCKET1/OBJECT1 s3://BUCKET2[/OBJECT2]
• s3cmd setacl s3://BUCKET[/OBJECT]
• s3cmd setpolicy FILE s3://BUCKET
• s3cmd delpolicy s3://BUCKET
• s3cmd setcors FILE s3://BUCKET
• s3cmd delcors s3://BUCKET
• s3cmd payer s3://BUCKET
• s3cmd multipart s3://BUCKET [Id]
• s3cmd abortmp s3://BUCKET/OBJECT Id
• s3cmd listmp s3://BUCKET/OBJECT Id
• s3cmd accesslog s3://BUCKET
• s3cmd sign STRING-TO-SIGN
• s3cmd signurl s3://BUCKET/OBJECT <expiry_epoch|+expiry_offset>
• s3cmd fixbucket s3://BUCKET[/PREFIX]
• s3cmd ws-create s3://BUCKET
• s3cmd ws-delete s3://BUCKET
• s3cmd ws-info s3://BUCKET
• s3cmd expire s3://BUCKET
• s3cmd setlifecycle FILE s3://BUCKET
• s3cmd dellifecycle s3://BUCKET
• s3cmd cflist
• s3cmd cfinfo [cf://DIST_ID]
• s3cmd cfcreate s3://BUCKET
• s3cmd cfdelete cf://DIST_ID
• s3cmd cfmodify cf://DIST_ID
• s3cmd cfinvalinfo cf://DIST_ID[/INVAL_ID]