https://github.com/mobydeck/s3-cli
Console S3 client
https://github.com/mobydeck/s3-cli
Last synced: 5 months ago
JSON representation
Console S3 client
- Host: GitHub
- URL: https://github.com/mobydeck/s3-cli
- Owner: mobydeck
- License: mit
- Created: 2026-01-12T00:17:14.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-12T00:19:08.000Z (5 months ago)
- Last Synced: 2026-01-12T04:43:22.325Z (5 months ago)
- Language: Go
- Homepage:
- Size: 27.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `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`](https://github.com/koblas/s3-cli), inspired by [`s3cmd`](https://github.com/s3tools/s3cmd), and aims to be a practical drop-in replacement for many everyday workflows.
## Features
- Compatible with [`s3cmd`](https://github.com/s3tools/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`:
```ini
[default]
access_key = foo
secret_key = bar
[profile1]
access_key = foo1
secret_key = bar1
```
Select a profile via CLI:
```bash
s3 --profile profile1 cp file1 s3://bucket/file1
s3 -p profile1 cp file1 s3://bucket/file1
```
Or via environment variable:
```bash
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:
```bash
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`):
```bash
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):
```bash
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:
```bash
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:
```bash
s3 del [--recursive] s3://bucket/key/on/s3/
```
### `rm`
Alias for `del`.
```bash
s3 rm [--recursive] s3://bucket/key/on/s3/
```
### `sync`
Sync between a local directory and S3.
```bash
s3 sync [--delete-removed] /path/to/folder/ s3://bucket/key/on/s3/
```
### `mv`
Move an object already stored in S3.
Example:
```bash
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 `
- `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]`