Amazon-S3

 view release on metacpan or  search on metacpan

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

      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(

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

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

=item B<get-bucket-policy>

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

Retrieves the bucket policy and emits it as formatted JSON.

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

=item B<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 C<--output> to specify another filename or C<--output -> to write
the object to standard output.

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>

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

=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