Guide
  1. Object Storage
  2. Clients and tooling
  3. Use the AWS CLI and SDKs with Object Storage

The AWS CLI and Object Storage

Amazon's AWS CLI is a command-line tool you can use to interface with Object Storage.

📘

  • If you haven't already, review Data integrity protections.
  • These instructions use AWS CLI version 2. Earlier versions may not work.

Set up the AWS CLI

Review these sections to install and configure the AWS CLI.

Prerequisite

You need an Object Storage access key, to grant the AWS CLI 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 the AWS CLI

To install the AWS CLI (version 2), see Install, update, and uninstall the AWS CLI and follow the instructions for your operation system. Currently, there isn't an official package in any package manager. So, you'll need to download and install the package manually.

You can can use either command set:

  • aws s3. This includes a small subset of all of the s3 commands and is easier to use.
  • aws s3api. This command-set includes every s3 operation and allows for advanced configurations.

We cover the use of both in this guide.

Configure the AWS CLI

  1. Run this command in your preferred terminal:

    aws configure

  2. When prompted, set these parameters:

    • AWS Access Key ID. This is your Object Storage access key.
    • AWS Secret Access Key. This is 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.
    • Default region name. Press enter without inputting any characters to keep the default us region. Don't change this, even if you use Object Storage in a region outside the United States.
    • Default output format. Press Enter without inputting any characters.

Additional resources

See the following guides from AWS for more details on configuring the CLI:

All commands require the endpoint URL

When using the AWS CLI 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:

aws s3 [command] --endpoint=[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 a few basic CLI commands you can use to interact with your buckets and objects.

List buckets

List all of your buckets in a region, based on its [endpoint-url]:

aws s3 ls --endpoint=[endpoint-url]

For example, to list all of your E3 endpoint buckets in the Seattle region, you could run this command:

aws s3 ls --endpoint=https://us-sea-9.linodeobjects.com

Create a bucket

Create a new bucket, by replacing [bucket-label] with a desired name:

aws s3 mb s3://[bucket-label] --endpoint=[endpoint-url]
📘

Bucket names have requirements

See Manage buckets for rules on naming the bucket.

For example, to create an E3 endpoint bucket with the label of example-bucket in the Seattle region, you could run this command:

aws s3 mb s3://example-bucket --endpoint=https://us-sea-9.linodeobjects.com

Delete a bucket

Delete a bucket, by replacing [bucket-label] with the name of the target bucket:

s3cmd rb s3://[bucket-label]

You can only use this command to delete a bucket if it's empty. To delete a bucket that has objects in it, include the --recursive (or -r) option and the --force (or -f) option:

s3cmd rb -r -f s3://[bucket-label]
🚧

This command is permanent

Only use this command if you're sure you want to delete everything in the target bucket.

Get object metadata

You can retrieve the metadata for an object, but not the object itself. Run the head-object command, replacing these variable values:

📘

Object Storage doesn't support the get-object-attributes command.

  • [bucket_label]. The name of the bucket containing the target object.
  • [object-key]. The name of the target object.
  • [endpoint-url]. https:// followed by the S3 endpoint.
aws s3api head-object --bucket [bucket-label] --key [object-key] --endpoint-url [endpoint-url]

For example, to retrieve metadata about the object named example-file, that's in an E3 endpoint bucket named example-bucket in the Seattle region, you would run this command:

aws s3api head-object --bucket example-bucket --key example-file --endpoint-url https://us-sea-9.linodeobjects.com

Multipart upload example

In the case of a multipart upload, you can get more information on the object by running the list-parts command, using the same values as the example above, but also including the upload-id:

aws s3api list-parts --bucket [bucket-label] --key [object-key] --upload-id [upload-id] --endpoint-url [endpoint-url]

You can get the [upload-id] value in the response after you upload the object using the create-multipart-upload command.

Updated 7 days ago

Did this page help you?