aws-s3api

Create bucket in a specific region

$ aws s3api create-bucket --bucket [bucket_name] --region [region] --create-bucket-configuration LocationConstraint=[region]

$ aws s3api delete-bucket --bucket [bucket_name]

$ aws s3api list-buckets

$ aws s3api list-objects --bucket [bucket_name] --query '[Contents[].{Key: Key, Size: Size]}'

$ aws s3api put-object --bucket [bucket_name] --key [object_key] --body [path/to/file]

$ aws s3api get-object --bucket [bucket_name] --key [object_key] [path/to/output_file]

$ aws s3api put-bucket-policy --bucket [bucket_name] --policy file://[path/to/bucket_policy.json]

$ aws s3api get-bucket-policy --bucket [bucket_name] --query Policy --output [json|table|text|yaml|yaml-stream] > [path/to/bucket_policy]

aws s3api <operation> [<parameters>]

Examples:
aws s3api create-bucket --bucket my-unique-bucket-name --create-bucket-configuration LocationConstraint=us-west-2
aws s3api get-object --bucket my-bucket --key my-file.txt my-local-file.txt
aws s3api put-object --bucket my-bucket --key new-file.txt --body ./local-file-to-upload.txt
aws s3api list-buckets

<operation>
    This is a required subcommand that specifies the exact Amazon S3 API operation to execute (e.g., create-bucket, list-buckets, get-object, put-object, delete-object, get-bucket-policy). Each operation has its own specific set of required and optional parameters.

--<parameter-name>
    General syntax for arguments specific to the chosen S3 API operation. These parameters directly correspond to the S3 API request elements. Common examples include --bucket (specifies the bucket name), --key (specifies the object key), --body (specifies the path to a file for upload), --create-bucket-configuration (often expects JSON for bucket creation details), --policy (expects JSON for bucket policies). Many complex parameters require a path to a JSON file (e.g., --policy file://policy.json).

--endpoint-url <url>
    Optional. Specifies a custom endpoint URL for the S3 service. Useful for testing or when using S3-compatible storage solutions.

--region <region>
    Optional. Specifies the AWS region to send the request to (e.g., us-east-1, eu-west-2). Overrides the default region configured in the AWS CLI profile.

--output <format>
    Optional. Specifies the output format of the command. Common formats include json (default), text, or table.

--query <jmespath-expression>
    Optional. Uses a JMESPath expression to filter and format the command output, allowing users to extract specific data from the JSON response.

aws s3api is a subcommand of the AWS Command Line Interface (CLI) that provides direct, low-level access to Amazon S3 service operations. Unlike the high-level aws s3 commands (e.g., cp, sync, ls) which simplify common file operations, s3api directly maps to the S3 REST API operations. This allows for fine-grained control over S3 resources, enabling users to perform actions such as creating buckets with specific region constraints, configuring detailed bucket policies, managing lifecycle rules, or interacting with object versioning at a programmatic level. It is particularly useful for advanced scripting, automation, and when specific S3 features not exposed by the simpler high-level commands are required. Users typically need to have precise knowledge of the S3 API parameters, often supplying input in JSON format and receiving output in JSON.

aws s3api commands are low-level and can be significantly more complex and verbose than their high-level aws s3 counterparts. They require a detailed understanding of the underlying S3 API operations and their specific parameters. Incorrect syntax or parameter values can lead to cryptic errors. For simple file transfers and basic bucket listings, the high-level aws s3 commands are generally preferred due to their simplicity. All s3api operations return JSON output by default, which may require further parsing for scripting purposes.

The AWS CLI offers two primary interfaces for interacting with S3: aws s3 and aws s3api. aws s3 commands (e.g., cp, sync, ls, rm) are designed for ease of use, abstracting away API complexity to simplify common file and bucket management tasks. They are ideal for everyday operations. Conversely, aws s3api commands provide a direct, one-to-one mapping to the Amazon S3 REST API. This low-level access is crucial for advanced scenarios where specific S3 features like detailed access control lists (ACLs), bucket policies, lifecycle rules, versioning configurations, or multi-part uploads with specific control are needed. While more complex to use, s3api is indispensable for robust scripting and automation of intricate S3 workflows.

The AWS Command Line Interface (CLI) was initially released in 2013 to provide a unified tool for managing AWS services. From its early versions, the s3api subcommand was integral, offering direct access to Amazon S3's REST API. This design choice allowed for both simplified, common S3 operations (via aws s3) and granular control over every S3 feature (via aws s3api), ensuring the CLI could cater to a wide range of use cases from basic file management to complex automation tasks requiring precise API interactions.

aws(1), aws s3(1) (refers to the high-level AWS CLI S3 commands), jq(1) (for parsing JSON output from aws s3api)