The s4cmd software is a command-line tool that can access Amazon S3-compatible storage services, such as Object Storage. It uses the Amazon S3 client in Amazon's boto3 library. Compared to the popular s3cmd tool, s4cmd is typically much faster, but it offers fewer options. and is less configurable. For many use cases, the Linode CLI or s3cmd may fit your needs better.

Set up s4cmd

Review these sections to install and configure s4cmd.

Prerequisite

You need an Object Storage access key, to grant s4cmd access to your Object Storage buckets and objects. See Manage access keys for instructions, if you don't already have one. Specifically, you'll need these values:

• The access key. After you create a key, a unique identifier is assigned to the key.
• The secret key. This is a unique secret that ​Akamai​ generates for the access key.

📘

The secret key is only displayed a single time, after you create the access key. So, if you don't know this value, you'll need to generate a new access key and be sure to store its secret key.

Install s4cmd

Select a tab for instructions on installing s4cmd on a specific operating system.

sudo pip install s4cmd

Configure credentials

You need to provide credentials that s4cmd can use to access your buckets and objects. These credentials are your Object Storage access key and its secret key.

By default, s4cmd looks for these credentials in the ~/.s3cfg file—the configuration file that s3cmd uses. The .s3cfg is stored in /home/<username>/.s3cfg on both Linux and macOS. Open this file in a text editor and add these lines, replacing these variable values:

[default]
access_key = YOUR_ACCESS_KEY
secret_key = YOUR_SECRET_KEY

• YOUR_ACCESS_KEY. Replace this with your Object Storage access key.
• YPUR_SECRET_KEY. Replace this with the secret key that was generated for your Object Storage access key. If you don't know this value, you'll need to generate a new access key.

👍

If you don't have s3cmd installed on your system, create /home/<username>/.s3cfg. Open it in a text editor and add these same lines.

All commands require the endpoint URL

When using s4cmd with a non-AWS service like Object Storage, you need to specify the endpoint URL in each command. You can do this by including the --endpoint parameter:

s4cmd ls --endpoint-url [endpoint-url]

When you're using the commands in this guide, always replace [endpoint-url] with the URL of the Object Storage endpoint where your bucket lives, or where you want to create it. If you don't know the URL:

1. See Supported endpoint types by region, and locate your specific endpoint type's Endpoint (S3 hostname), based on its region.
2. Format it as https://[S3 hostname].

For example, if you're using an E3 endpoint in Seattle, WA USA, its endpoint URL would be https://us-sea-9.linodeobjects.com.

Example commands

Here are some basic s4cmd commands you an use to interact with your buckets and objects.

List buckets

List all buckets in a specific region, as defined in your [endpoint-url]:

s4cmd ls --endpoint-url [endpoint-url]

To see all of your E3 endpoint buckets in Seattle, this command would be:

s4cmd ls --endpoint-url https://us-sea-9.linodeobjects.com

Create a bucket

Create a new bucket, replacing [bucket-label] with a desired name for it. The bucket will live in the in the region defined in your [endpoint-url]:

s4cmd mb s3://[bucket-label] --endpoint-url [endpoint-url]

This example creates a new E3 endpoint bucket named "example-bucket" in Seattle:

s4cmd mb s3://example-bucket --endpoint-url https://us-sea-9.linodeobjects.com

Delete a bucket

Currently, you can't delete a bucket using s4cmd. However, you can delete a bucket with s3cmd.

List objects

List all objects in a specific bucket. Replace these variable values:

• [bucket-label]. The name of the bucket where the target objects are stored.
• [path]. Optionally include the pseudo path in the bucket where the target files reside. (This only applies if the files aren't in the root of the bucket.)
• [endpoint-url]. Your S3 endpoint formatted as an endpoint url.

s4cmd ls s3://[bucket-label]/[path] --endpoint-url [endpoint-url]

This example lists all objects in the bucket called "example-bucket", located in the Newark region:

s4cmd ls s3://example-bucket/ --endpoint-url https://us-east-1.linodeobjects.com

Upload an object

Add a file as an object to a specific bucket. Replace these variable values:

• [file-path]. The complete path and filename for the file you want to upload.
• [bucket-label]. The name of the target bucket.
• [path]. Optionally include the pseudo path in the bucket where you want the file to reside. (This only applies if you don't want the file to live in the root of the bucket.)
• [endpoint-url]. Your S3 endpoint formatted as an endpoint url.

s4cmd put [file-path] s3://[bucket-label]/[path] --endpoint-url [endpoint-url]

This example uploads the file "file.txt" from the active directory on the local system, to "example-bucket", located in the Newark region:

s4cmd put file.txt s3://example-bucket/ --endpoint-url https://us-east-1.linodeobjects.com

🚧

If you upload an object that uses non-standard special characters or unusual ASCII/Unicode characters in its name, the upload may fail. This includes the characters: : " ' < > & + =.

Download an object or directory

To download a directory or specific object, replace these variable values in the command:

• [bucket-label]. The name of the target bucket.
• [path]. The full pseudo path to the directory on the bucket you want to download, or the full pseudo path and filename of the specific object to download.
• [endpoint-url]. Your S3 endpoint formatted as an endpoint url.

s4cmd get s3://[bucket-label]/[path] --endpoint-url [endpoint-url]

This example downloads the file "file.txt" from "example-bucket", located in the Newark region:

s4cmd get s3://example-bucket/file.txt --endpoint-url https://us-east-1.linodeobjects.com

Delete an object or directory

To delete a directory or a specific object, replace the variable values in the command:

• [bucket-label]. The name of the bucket where the target object lives.
• [path]. The full pseudo path to the target directory to delete, or the full pseudo path and filename of the specific object to delete.
• [endpoint-url]. Your S3 endpoint formatted as an endpoint url.

s4cmd rm s3://[bucket-label]/[path] --endpoint-url [endpoint-url]

This example deletes all the files within the "files" directory on "example-bucket" that's located in the Newark data center:

s4cmd del s3://example-bucket/files/ --endpoint-url https://us-east-1.linodeobjects.com

Additional commands

Additional commands and options for s4cmd can be found on the s4cmd Readme page or by running s4cmd --help.