s3cli

Simple CLI for S3 operations using AWS SDK. Compatible with Supabase Storage, AWS S3, MinIO and other S3-compatible providers.

Installation

npm install
npm run build

Configuration

The quickest way to get started is with the interactive init command:

s3cli init

This creates ~/.s3cli/.env with your credentials (permissions set to 0600).

Config resolution order

1. Local .env — in the current directory (takes precedence)
2. Global ~/.s3cli/.env — shared across all projects

If no config is found, s3cli will prompt you to run s3cli init.

Manual setup

You can also create the .env file manually:

S3_ENDPOINT=https://your-project.supabase.co/storage/v1/s3
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_USE_SSL=true
S3_BUCKET=your-bucket
S3_REGION=eu-central-1
S3_PATH_STYLE=true

Usage

List files

# List all files
npm run start -- ls

# List files with prefix
npm run start -- ls folder/

Upload file

npm run start -- upload file.txt backup/file.txt

By default, s3cli auto-detects the Content-Type based on the file extension. You can override it manually if needed:

npm run start -- upload file.txt backup/file.txt --content-type text/plain

Download file

# Download keeping original name
npm run start -- get backup/file.txt

# Download with new name
npm run start -- get backup/file.txt restored-file.txt

Delete file

npm run start -- rm backup/file.txt

Generate signed URL

# URL valid for 1 hour (default)
npm run start -- url backup/file.txt

# URL valid for 24 hours (86400 seconds)
npm run start -- url backup/file.txt 86400

# Only the URL (no message, ideal for pipes)
npm run start -- url backup/file.txt --quiet

# Automatically shortened URL (requires S3CLI_SHORTENER_CMD)
npm run start -- url backup/file.txt --shorten

# Combined: short and clean URL
npm run start -- url backup/file.txt -qs

URL Shortener

To use the --shorten flag, configure the S3CLI_SHORTENER_CMD environment variable with the command to use:

# In .env file
S3CLI_SHORTENER_CMD=shortener

# Or export directly
export S3CLI_SHORTENER_CMD=shortener

The command should accept a URL as argument and output the shortened URL to stdout. Example with shortener:

# Direct usage
shortener "https://example.com/long/url"
# Output: https://short.io/abc123

# With s3cli
s3cli url file.txt --shorten
# Output: https://short.io/xyz789

Commands

| Command | Description | |---------|-------------| | init | Interactive setup — creates ~/.s3cli/.env | | ls [prefix] | List files in the bucket | | upload <local> <remote> | Upload a file (auto-detects Content-Type; override with --content-type) | | get <remote> [local] | Download a file | | rm <remote> | Delete a file | | url <remote> [expiry] | Generate a signed URL (expiry in seconds) |

Global Installation

To use s3cli as a global command:

npm run build
npm link

Then:

s3cli ls
s3cli upload file.txt remote/file.txt
s3cli url remote/file.txt 3600

License

MIT