Introduction

Have you tried to find documentation for AWS CLI’s S3 functionality and run into two commands that both perform S3 related operations: s3 and s3api?

Almost every other AWS service only has one command in the CLI, so having two commands is unusual and can be confusing.

In this article, we will take a look at both of these commands and their differences.

s3api

The subcommands for a particular AWS CLI command are generated from the service’s API. The service API is defined in a JSON model. The s3api command is generated via S3’s service API. Therefore, you will find every operation that is exposed via the S3 API itself, like:

  • create-bucket: Creates a new bucket
  • list-objects-v2: List objects in a bucket.

The output from running these commands is in the standard JSON format that you expect from AWS APIs.


aws s3 list-buckets

{
    "Buckets": [
        {
            "Name": "your-bucket-1",
            "CreationDate": "2020-01-23T05:13:09+00:00"
        },
        {
            "Name": "your-bucket-2",
            "CreationDate": "2021-05-11T03:21:31+00:00"
        }
    ]
}

The list of all commands supported by s3api is available here.

s3

The s3 commands are a set of commands that were designed to make it easier to interact and manage your files on S3.

The operations supported by the s3:

   o cp
   o ls
   o mb
   o mv
   o presign
   o rb
   o rm
   o sync
   o website

For e.g., the cp subcommand is used to copy a local file to S3 or vice versa. However, the cp command doesn’t directly map to any API in S3. Instead, it is a higher level functionality that is built on lower-level APIs like those supported by s3api.

The output of these commands has also been formatted so that it’s easier to understand. For e.g., the output of aws s3 ls:


aws s3 ls
2020-01-22 21:13:09 your-bucket-1
2021-05-10 20:21:31 your-bucket-2

s3api vs s3

Both commands provide different functionality. Whereas s3api supports all of the functionality provided by S3, s3 supports a limited and higher-level set of functionality.

Generally, the s3 command is easier to use and if your use-case is solved by using the s3 command, then you should go ahead and use that.

If your use-case isn’t supported by the s3 command, then you need to use the s3api subcommand.

If you need a lot more flexibility, then s3api might be the better option for you.

IAM permissions

A key difference between the commands is that since s3api has a direct mapping with S3 service API’s, you can provide IAM permissions for any action that you want.

However, since various s3 commands are built on top of other low-lvel API’s, you will need to provide IAM permissions for those actions.

Another thing to note is that since the s3 command is built on top of other low-level functionality,

For e.g., the cp command uses the UploadPart under the hood, so you would need to provide that permission in your IAM policy.