Amazon Simple Storage Service (S3) is a highly scalable and secure cloud storage service offered by Amazon Web Services (AWS). One of the command-line tools provided by AWS CLI (Command Line Interface) for interacting with S3 is the aws s3 ls command. This command allows you to list and retrieve information about S3 buckets, folders, and files. In this article, we will explore eight different use cases of the aws s3 ls command, along with their code examples and explanations.

Use Case 1: List All Buckets

To list all available S3 buckets, you can simply run the following command:

aws s3 ls

Motivation: This use case is useful when you want to quickly retrieve a list of all the S3 buckets in your AWS account.

Argument Explanation: The command aws s3 ls does not require any additional arguments. It automatically returns a list of all the S3 buckets associated with the configured AWS account.

Example Output:

2021-08-01 12:00:00 my-bucket-1
2021-08-02 09:30:00 my-bucket-2
2021-08-03 15:45:00 my-bucket-3

Use Case 2: List Files and Folders in the Root of a Bucket

To list files and folders in the root of a specific S3 bucket, you can use the following command:

aws s3 ls s3://bucket_name

Motivation: This use case allows you to retrieve a list of files and folders located directly in the root of a specific S3 bucket.

Argument Explanation: The argument s3://bucket_name is the URI of the S3 bucket. You need to replace bucket_name with the actual name of the bucket you want to list.

Example Output:

2021-08-01 12:00:00         1234 file1.txt
2021-08-02 09:30:00        5678 file2.txt
2021-08-03 15:45:00        9012 folder1/

Use Case 3: List Files and Folders directly inside a Directory

To list files and folders directly inside a specific directory within a bucket, you can run the following command:

aws s3 ls bucket_name/path/to/directory/

Motivation: This use case is useful when you want to retrieve a list of files and folders located directly inside a specific directory in an S3 bucket.

Argument Explanation: The argument bucket_name/path/to/directory/ specifies the URI of the directory within the bucket. Replace bucket_name with the bucket name and path/to/directory with the actual path to the directory.

Example Output:

2021-08-01 12:00:00         1234 file3.txt
2021-08-02 09:30:00        5678 file4.txt

Use Case 4: List All Files in a Bucket

To list all the files within a specific S3 bucket, including files inside subdirectories, you can use the --recursive option:

aws s3 ls --recursive bucket_name

Motivation: This use case is helpful when you want to retrieve a complete list of all the files present in an S3 bucket, including files in subdirectories.

Argument Explanation: The --recursive option tells the command to list files recursively, meaning it goes through all subdirectories within the bucket as well. bucket_name should be replaced with the name of the bucket you want to list.

Example Output:

2021-08-01 12:00:00         1234 file1.txt
2021-08-02 09:30:00        5678 file2.txt
2021-08-03 15:45:00        9012 folder1/file3.txt
2021-08-03 16:30:00        3456 folder2/file4.txt

Use Case 5: List All Files in a Path with a Given Prefix

To list all files within a specific path in an S3 bucket, filtered by a prefix, you can use the --recursive option along with the prefix:

aws s3 ls --recursive bucket_name/path/to/directory/prefix

Motivation: This use case is helpful when you want to retrieve a list of files within a specific path in an S3 bucket, but you only want to include files with a given prefix.

Argument Explanation: The argument bucket_name/path/to/directory/prefix specifies the path within the bucket along with the prefix to be matched. Replace bucket_name with the bucket name, path/to/directory with the actual path to the directory, and prefix with the desired prefix.

Example Output:

2021-08-01 12:00:00         1234 folder1/file1.txt
2021-08-02 09:30:00        5678 folder2/file1.txt

Use Case 6: Display Help

To display the help information and available options for the aws s3 ls command, you can run the following:

aws s3 ls help

Motivation: This use case is useful when you need a quick reference guide for the command’s syntax and available options.

Argument Explanation: The argument help is used to retrieve the help information for the aws s3 ls command.

Example Output:

NAME
      ls -

SYNOPSIS
      s3 ls [options] <S3Uri>

DESCRIPTION
      List buckets, folders, or objects under a prefix or all S3 URIs recursively.

OPTIONS
      --profile <value>
          Use a named profile configured in the shared credentials file. 

      --endpoint-url <value>
          Override the default endpoint URL (hostname) for a service or a specific command.

      --region <value>
          The region to use.

      --human-readable (boolean)
          Displays file sizes in human-readable format.

      --summarize (boolean)
          Displays a summary of the number of files and folders.

      --recursive (boolean)
          Command is performed on all files or objects under the specified directory or prefix.

      ...

Conclusion

The aws s3 ls command is a versatile tool for listing and retrieving information about S3 buckets, folders, and files. In this article, we discussed eight different use cases and provided code examples and explanations for each. By mastering this command, you can easily navigate and explore the contents of your S3 buckets, making it an essential skill for managing your AWS infrastructure.