Amazon-S3

 view release on metacpan or  search on metacpan

lib/Amazon/S3/CLI.pm  view on Meta::CPAN

  my ($self) = @_;

  my $buckets = $self->get_s3->buckets();

  if ( !$buckets || !@{ $buckets->{buckets} // [] } ) {
    print {*STDOUT} "no buckets\n";

    return $SUCCESS;
  }

  return $self->_list_buckets($buckets);
}

########################################################################
sub _list_buckets {
########################################################################
  my ( $self, $buckets ) = @_;

  if ( $self->get_format eq 'json' ) {
    my $data = {
      owner_id => $buckets->{owner_id},
      buckets  =>
        { map { $_->bucket => { region => $_->region, creation_date => $_->creation_date, } } @{ $buckets->{buckets} } },
    };

    print {*STDOUT} JSON::PP->new->pretty->allow_blessed->convert_blessed->encode($data);

    return $SUCCESS;
  }

  my $data = [ sort { $a->bucket cmp $b->bucket } @{ $buckets->{buckets} } ];

  if ( $self->get_ascii_table && $self->get_format eq 'table' ) {
    my $t = Text::ASCIITable->new( { headingText => 'Bucket Listing', } );

    $t->setCols( qw(Bucket Region), 'Creation Date' );

    foreach my $b ( @{$data} ) {
      $t->addRow( $b->bucket, $b->region, $b->creation_date, );
    }

    print {*STDOUT} $t;

    return $SUCCESS;
  }

  print {*STDOUT} "Bucket,Region,CreationDate\n";

  foreach my $b ( @{$data} ) {
    print {*STDOUT} sprintf qq{"%s","%s","%s"\n}, $b->bucket, $b->region, $b->creation_date;
  }

  return $SUCCESS;
}

########################################################################
sub init {
########################################################################
  my ($self) = @_;

  my %endpoint = choose {
    return ( host => $self->get_host )
      if defined $self->get_host;

    return ( endpoint_url => $self->get_endpoint_url )
      if $self->get_endpoint_url;

    return ();
  };

  $self->set_ascii_table(
    eval {
      require Text::ASCIITable;
      1;
    }
  );

  die "ERROR: --format must be one of json, text or table\n"
    if none { $self->get_format eq $_ } qw(json text table);

  my %credentials;

  my $has_amazon_credentials = eval {
    require Amazon::Credentials;
    1;
  };

  if ($has_amazon_credentials) {
    $credentials{credentials} = Amazon::Credentials->new(
      { $self->get_profile
        ? ( profile => $self->get_profile )
        : (),
      }
    );
  }
  else {
    die "ERROR: --profile requires Amazon::Credentials\n"
      if $self->get_profile;

    $credentials{aws_access_key_id}     = $ENV{AWS_ACCESS_KEY_ID};
    $credentials{aws_secret_access_key} = $ENV{AWS_SECRET_ACCESS_KEY};
    $credentials{token}                 = $ENV{AWS_SESSION_TOKEN};
  }

  my $s3 = Amazon::S3->new(
    { %credentials,
      debug            => $ENV{DEBUG},
      raise_error      => $TRUE,
      region           => $self->get_region,
      logger           => $self->get_logger,
      dns_bucket_names => $self->get_dns_bucket_names // $FALSE,
      %endpoint,
      defined $self->get_secure ? ( secure => $self->get_secure ) : (),
    }
  );

  $self->set_s3($s3);

  return;
}

########################################################################
sub confirm {
########################################################################
  my ( $self, $prompt ) = @_;

  print "$prompt [y/N] ";

  my $answer = <STDIN>;
  return $FALSE
    if !defined $answer;

  chomp $answer;

  return $answer =~ /\Ay(?:es)?\z/i ? $TRUE : $FALSE;
}

########################################################################
sub guess_content_type {
########################################################################
  my ($filename) = @_;

  my $has_mmagic = eval { require File::MimeInfo::Magic; 1; };

  return 'application/octet-stream'
    if !$has_mmagic || !$filename || !-f $filename;

  my $content_type = eval { return File::MimeInfo::Magic::mimetype($filename); };

  return $content_type
    if !$EVAL_ERROR && $content_type;

  return 'application/octet-stream';
}

########################################################################
sub main {
########################################################################

  my %default_options = (
    output => $EMPTY,
    region => 'us-east-1',
    format => 'text',
  );

  my @option_specs = qw(
    availability-zone=s
    bucket-name|b=s
    content-type=s
    debug
    dns-bucket-names
    endpoint-url|u=s
    force|f
    format|F=s
    help|h
    host|H=s
    key|k=s
    modified-since|m=s
    output|o=s
    prefix=s
    profile|p=s
    range|R=s
    region|r=s
    secure|s
    version-id=s
  );

  my %commands = (
    'add-key'                  => \&cmd_add_key,
    'copy-key'                 => \&cmd_copy_key,
    'create-bucket'            => \&cmd_create_bucket,
    'delete-key'               => \&cmd_delete_key,
    'empty-bucket'             => \&cmd_empty_bucket,
    'get-key'                  => \&cmd_get_key,
    'get-bucket-policy'        => \&cmd_get_bucket_policy,
    'get-bucket-acl'           => \&cmd_get_bucket_acl,
    'get-bucket-policy-status' => \&cmd_get_bucket_policy_status,
    'list-bucket-keys'         => \&cmd_list_bucket_keys,
    'list-directory-buckets'   => \&cmd_list_directory_buckets,
    'list-keys'                => 'list-bucket-keys',
    'list-object-versions'     => \&cmd_list_object_versions,
    'remove-bucket'            => \&cmd_remove_bucket,
    'list-buckets'             => \&cmd_list_buckets,
  );

  return __PACKAGE__->new(
    commands        => \%commands,
    option_specs    => \@option_specs,
    default_options => \%default_options,
    abbreviations   => $TRUE,
    extra_options   => [qw(s3 secure ascii_table)],
  )->run;
}

1;

__END__

## no critic

=pod

=encoding utf8

=head1 NAME

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

=head1 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

=head1 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.

=head1 DESCRIPTION

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

It is intended as a convenient command-line companion to the library,
not as a replacement for the complete AWS CLI or C<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.

=head2 Commands

=over

=item B<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 C<--bucket-name>. If
C<object-name> is omitted, the filename is used as the object key.

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

=item B<copy-key>

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

Copies an object to another key in the same bucket.

=item B<create-bucket>

  amzn-s3-cli create-bucket bucket-name

Creates a bucket.

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

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

=item B<delete-key>

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

Deletes an object.

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

=item B<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
C<--force> to suppress the prompt.

=item B<get-bucket-acl>

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

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

lib/Amazon/S3/CLI.pm  view on Meta::CPAN


Use C<--version-id> to retrieve a specific object version.

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

=item B<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 C<--prefix>.

C<list-keys> is an alias for C<list-bucket-keys>.

=item B<list-buckets>

  amzn-s3-cli list-buckets

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

=item B<list-directory-buckets>

  amzn-s3-cli list-directory-buckets

Lists S3 Express One Zone directory buckets.

=item B<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.

=item B<remove-bucket>

  amzn-s3-cli remove-bucket bucket-name

Removes a bucket.

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

=back

=head2 Options

Most commands accept the bucket name positionally or through
C<--bucket-name>.

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

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

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

=head1 OPTIONS

=over

=item B<--availability-zone>

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

=item B<--bucket-name>, B<-b>

Specifies the bucket name.

=item B<--content-type>

Specifies the content type used when adding an object.

=item B<--debug>

Enables debug logging.

=item B<--dns-bucket-names>

Enables DNS-style bucket addressing.

=item B<--endpoint-url>, B<-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.

=item B<--force>, B<-f>

Suppresses confirmation prompts for destructive operations.

=item B<--format>, B<-F>

Selects the output format.

 text
 json
 table

The default is C<text>.

Table output requires L<Text::ASCIITable>.

=item B<--help>, B<-h>

Displays command help.

=item B<--host>, B<-H>

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

C<--endpoint-url> is preferred for alternate endpoints.

=item B<--key>, B<-k>

Specifies an object key.

=item B<--modified-since>, B<-m>

Supplies an C<If-Modified-Since> condition to C<get-key>.

=item B<--output>, B<-o>

Specifies where C<get-key> writes its result.

Use C<-> to write object data to standard output.

=item B<--prefix>

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

=item B<--profile>, B<-p>

Selects an AWS credential profile.

This option requires L<Amazon::Credentials>.

=item B<--range>, B<-R>

Requests a byte range with C<get-key>.

Specify only the range:

  --range 0-1023

=item B<--region>, B<-r>

Specifies the AWS region.

The default is C<us-east-1>.

=item B<--secure>, B<-s>

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

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

=item B<--version-id>

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

=back

=head1 AUTHENTICATION

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

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

Without L<Amazon::Credentials>, credentials are read from:

  AWS_ACCESS_KEY_ID
  AWS_SECRET_ACCESS_KEY
  AWS_SESSION_TOKEN

=head1 S3-COMPATIBLE SERVICES

An alternate S3 endpoint may be selected with C<--endpoint-url>:

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

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

=head1 OPTIONAL DEPENDENCIES

=over

=item L<Amazon::Credentials>

Provides credential discovery and named profile support.

=item L<File::MimeInfo::Magic>

Provides MIME type detection for C<add-key>.

=item L<Text::ASCIITable>

Provides C<--format table> output.

=back

=head1 SEE ALSO

L<Amazon::S3>

L<Amazon::S3::Bucket>

L<Amazon::S3::BucketV2>

L<Amazon::Credentials>

=head1 LICENSE

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

=head1 AUTHOR

Rob Lauer - E<lt>rlauer@treasurersbriefcase.comE<gt>

=cut



( run in 1.775 second using v1.01-cache-2.11-cpan-1bcd28dbaf1 )