/ 
Amazon-S3-2.1.2
⭐ Starred 2 / Amazon::S3::CLI

NAME

Amazon::S3::CLI - command line interface for common S3 operations

SYNOPSIS

# list buckets in tabular format
amzn-s3-cli list-buckets --profile sandbox --format table

# list keys in JSON format
amzn-s3-cli list-keys test-bucket --format json

# create a new bucket on LocalStack
amzn-s3-cli create-bucket my-bucket --endpoint-url http://localhost:4566 --profile localstack

# add a key using the filename as the object name
amzn-s3-cli add-key --bucket-name my-bucket some-file

# add a key with a different object name
amzn-s3-cli add-key --bucket-name my-bucket some-file project-alpha/some-file

# retrieve an object
amzn-s3-cli get-key my-bucket project-alpha/some-file

# delete an object
amzn-s3-cli delete-key --bucket-name my-bucket some-file

# inspect bucket configuration
amzn-s3-cli get-bucket-policy --bucket-name my-bucket
amzn-s3-cli get-bucket-policy-status --bucket-name my-bucket
amzn-s3-cli get-bucket-acl --bucket-name my-bucket

USAGE

usage: amzn-s3-cli [options] command [arguments]

Common commands:

add-key                  Add an object
copy-key                 Copy an object
create-bucket            Create a bucket
delete-key               Delete an object
empty-bucket             Empty a bucket
get-bucket-acl           Retrieve a bucket ACL
get-bucket-policy        Retrieve a bucket policy
get-bucket-policy-status Retrieve bucket policy status
get-key                  Retrieve an object
list-bucket-keys         List objects
list-buckets             List buckets
list-directory-buckets   List directory buckets
list-object-versions     List object versions
remove-bucket            Remove a bucket

Use:

amzn-s3-cli --help

for command and option documentation.

DESCRIPTION

Amazon::S3::CLI provides the amzn-s3-cli command for performing common Amazon S3 operations using Amazon::S3.

It is intended as a convenient command-line companion to the library, not as a replacement for the complete AWS CLI or aws s3api command surface.

The CLI supports common bucket and object operations and can also be used with S3-compatible services by specifying an alternate endpoint.

Commands

add-key
amzn-s3-cli add-key bucket-name filename [object-name]

Adds a file to a bucket.

The bucket may alternatively be supplied with --bucket-name. If object-name is omitted, the filename is used as the object key.

The content type may be supplied with --content-type. Otherwise the CLI attempts to determine the MIME type with File::MimeInfo::Magic, when installed, and falls back to application/octet-stream.

copy-key
amzn-s3-cli copy-key bucket-name key new-key

Copies an object to another key in the same bucket.

create-bucket
amzn-s3-cli create-bucket bucket-name

Creates a bucket.

Use --region to select a region other than us-east-1.

--availability-zone may be used to create an S3 Express One Zone directory bucket.

delete-key
amzn-s3-cli delete-key bucket-name key

Deletes an object.

Use --version-id to delete a specific version from a versioned bucket.

empty-bucket
amzn-s3-cli empty-bucket bucket-name

Removes all object versions, delete markers, and incomplete multipart uploads from a bucket.

The command prompts for confirmation before deleting data. Use --force to suppress the prompt.

get-bucket-acl
amzn-s3-cli get-bucket-acl bucket-name

Retrieves the bucket ACL and emits the decoded result as JSON.

get-bucket-policy
amzn-s3-cli get-bucket-policy bucket-name

Retrieves the bucket policy and emits it as formatted JSON.

get-bucket-policy-status
amzn-s3-cli get-bucket-policy-status bucket-name

Retrieves the public-access status calculated from the bucket policy and emits the decoded result as JSON.

get-key
amzn-s3-cli get-key bucket-name key

Retrieves an object.

By default the object is written to a file using the basename of the object key.

Use --output to specify another filename or --output - to write the object to standard output.

Use --version-id to retrieve a specific object version.

Use --range to request a byte range and --modified-since to add an If-Modified-Since condition.

list-bucket-keys
amzn-s3-cli list-bucket-keys bucket-name [prefix]

Lists all objects in a bucket using the ListObjectsV2 API.

A prefix may alternatively be supplied with --prefix.

list-keys is an alias for list-bucket-keys.

list-buckets
amzn-s3-cli list-buckets

Lists general-purpose S3 buckets available to the current credentials.

list-directory-buckets
amzn-s3-cli list-directory-buckets

Lists S3 Express One Zone directory buckets.

list-object-versions
amzn-s3-cli list-object-versions bucket-name [prefix]

Lists object versions in a bucket.

The listing includes the object key, size, last-modified timestamp, latest-version indicator, and version ID.

remove-bucket
amzn-s3-cli remove-bucket bucket-name

Removes a bucket.

The bucket must satisfy normal S3 deletion requirements. Use empty-bucket first when necessary.

Options

Most commands accept the bucket name positionally or through --bucket-name.

Output-producing commands generally support text, json, and table formats. Table output requires Text::ASCIITable.

Credentials are discovered through Amazon::Credentials when that module is installed. Otherwise the CLI uses the standard AWS credential environment variables.

Use --endpoint-url when working with an alternate S3-compatible service such as LocalStack.

OPTIONS

--availability-zone

Specifies an Availability Zone when creating an S3 Express One Zone directory bucket.

--bucket-name, -b

Specifies the bucket name.

--content-type

Specifies the content type used when adding an object.

--debug

Enables debug logging.

--dns-bucket-names

Enables DNS-style bucket addressing.

--endpoint-url, -u

Specifies the complete S3 service endpoint URL.

For example:

--endpoint-url http://localhost:4566

The URL scheme determines whether HTTP or HTTPS is used.

--force, -f

Suppresses confirmation prompts for destructive operations.

--format, -F

Selects the output format.

text
json
table

The default is text.

Table output requires Text::ASCIITable.

--help, -h

Displays command help.

--host, -H

Specifies the S3 service host using the legacy host configuration mechanism.

--endpoint-url is preferred for alternate endpoints.

--key, -k

Specifies an object key.

--modified-since, -m

Supplies an If-Modified-Since condition to get-key.

--output, -o

Specifies where get-key writes its result.

Use - to write object data to standard output.

--prefix

Limits object listing commands to keys beginning with the specified prefix.

--profile, -p

Selects an AWS credential profile.

This option requires Amazon::Credentials.

--range, -R

Requests a byte range with get-key.

Specify only the range:

--range 0-1023
--region, -r

Specifies the AWS region.

The default is us-east-1.

--secure, -s

Controls secure transport when host-based endpoint configuration is used.

When --endpoint-url is supplied, the URL scheme determines the transport.

--version-id

Specifies an object version ID for get-key or delete-key.

AUTHENTICATION

If Amazon::Credentials is installed, amzn-s3-cli uses it for credential discovery and supports named profiles:

amzn-s3-cli list-buckets --profile sandbox

Without Amazon::Credentials, credentials are read from:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN

S3-COMPATIBLE SERVICES

An alternate S3 endpoint may be selected with --endpoint-url:

amzn-s3-cli list-buckets --endpoint-url http://localhost:4566 --profile localstack

This is useful for LocalStack and other S3-compatible services.

OPTIONAL DEPENDENCIES

Amazon::Credentials

Provides credential discovery and named profile support.

File::MimeInfo::Magic

Provides MIME type detection for add-key.

Text::ASCIITable

Provides --format table output.

SEE ALSO

Amazon::S3

Amazon::S3::Bucket

Amazon::S3::BucketV2

Amazon::Credentials

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Rob Lauer - <rlauer@treasurersbriefcase.com>