Commands¶

Tip

Most commands support output redirection using “|”, “>” and “>>”.

New in version 0.1.11.

Some commands might return with an error message like this:

--> put -m _files/100mbfile 100mbfile
error: transfer failed...
    hint: An error occurred (NotImplemented) when calling the
    CreateMultipartUpload operation: The request requires
    functionality that is not implemented in the current release

In most cases, the hint is related to the storage service connected. The error shown here for example is caused by the connected storage service not supporting multipart upload.

help¶

--> help [command] | ? [command]

List the available commands or show help for the named command.

acl¶

--> acl -b|-o name [-g user permission [, user permission]*] [-s canned ACL]

Set Access Control Lists on a bucket or an object

-b name = bucket

-o name = object (needs to start with a “/”)

-g set per-user permission(s)

permissions is one of full_control, write, write_acp,

read, read_acp

-s set canned ACL

a canned ACLs is one of private, public-read,

public-read-write, authenticated-read

user is either:

for AWS: a user’s canonical ID
for HCP: a local HCP user name or an Active Directory user
(if HCP is integrated with AD) like this: aduser@domain.com
for other S3 storage: refer to the respective manual on how to
specify its users
and for all S3 stores: one of allusers, authenticateduser,
logdelivery

If neither -g nor -s is given, list the actual ACLs
-g and -s are exclusive
If any specifier holds characters outside the ascii alphabet and the underscore, surrond it with “quotation marks”

Changed in version 0.1.15: object ACLs completed

attach¶

--> attach [-h] bucket

Attach the bucket to work with.

positional arguments:
  bucket      the bucket's name

optional arguments:
  -h, --help  show this help message and exit

Changed in version 0.1.5: Renamed from bucket.

bucket¶

--> bucket [-h] [-c | -r] [-v] bucket

Create or remove a bucket, toggle versioning, show versioning setting when no options are set.

positional arguments:
  bucket      the bucket's name

optional arguments:
  -h, --help  show this help message and exit
  -c          create BUCKET
  -r          remove BUCKET
  -v          toggle versioning

Without any flags, the bucket's versioning status is shown

New in version 0.1.9: Replaces mkbucket and rmbucket.

bye¶

--> bye [-h]

Exit hs3sh gracefully.

optional arguments:
  -h, --help  show this help message and exit

clear¶

--> clear [-h]

Clear screen.

optional arguments:
  -h, --help  show this help message and exit

New in version 1.2.1.

config¶

--> ?config
usage: config [-h] [-s {mpu_size,mpu_threads}] [-v [VALUE]]

Get or set configuration item values

optional arguments:
  -h, --help            show this help message and exit
  -s {mpu_size,mpu_threads}
                        the configuration items to set
  -v [VALUE]            the (integer) value to set.

New in version 1.1.3.

Changed in version 1.2.1: renamed from set

connect¶

--> connect [-h] profile

Connect to an S3 endpoint using profile profile.

positional arguments:
  profile     a profile configured in the config file

optional arguments:
  -h, --help  show this help message and exit

Changed in version 0.1.5: Changed to use a profile to connect.

cp¶

--> cp [-h] [-v VERSIONID] sourceobject targetobject [meta ...]

Request the S3 service to server-side copy an object.

positional arguments:
  sourceobject  name (key) of the object to copy
  targetobject  name (key) of the target
  meta          format is: "key:value". Proving meta will replace eventually existing metadata in sourceobject with what is given as meta in targetobject

optional arguments:
  -h, --help    show this help message and exit
  -v VERSIONID  sourceobject's versionId. Will create a copy of the specified object version

debug¶

--> debug [-h] [command] [args ...]

Without "cmd [args]", toggle debug mode globally, with "cmd [args]", toggle debug mode for that command, only.

positional arguments:
  command     the command to run
  args        (optional) arguments

optional arguments:
  -h, --help  show this help message and exit

get¶

--> get [-h] [-m] [-v VERSIONID] object [localfile]

Get (download) an object.

positional arguments:
  object        name (key) of the object to download
  localfile     name of the local file to store the download (if not given, the source object's name will be used

optional arguments:
  -h, --help    show this help message and exit
  -m            request a multipart download
  -v VERSIONID  sourceobject's versionId. Will download the specified version

Changed in version 1.1.3: Added -m flag and enabled multipart download

getbl¶

--> getbl [-h] bucket

Get the location for bucket.

positional arguments:
  bucket      the bucket's name

optional arguments:
  -h, --help  show this help message and exit

New in version 1.2.0.

lcd¶

--> lcd [-h] [localdirectory]

Change the local working directory to localdirectory (or to home directory, if localdirectory isn't given).

positional arguments:
  localdirectory  the local directory

optional arguments:
  -h, --help      show this help message and exit

New in version 1.2.1.

lls¶

--> lls [-h] [localdirectory]

List contents of local path.

positional arguments:
  localdirectory  the local directory to be listed

optional arguments:
  -h, --help      show this help message and exit

New in version 1.2.1.

lpwd¶

--> lpwd [-h]

Print the local working directory.

optional arguments:
  -h, --help  show this help message and exit

New in version 1.2.1.

ls¶

 --> ls [-h] [-a] [-e] [-m] [-v] [prefix]

List the objects within the active bucket.

positional arguments:
  prefix      list objects starting with the prefix

optional arguments:
  -h, --help  show this help message and exit
  -a          print object acls
  -e          print object etags
  -m          print object metadata
  -v          print object versions

Changed in version 1.1.7: Added -e flag

Changed in version 0.1.9: Added -a flag

lsb¶

--> lsb [-h] [-a]

List the buckets available through the connected endpoint.

optional arguments:
  -h, --help  show this help message and exit
  -a          print bucket acls

Changed in version 0.1.4: Added -a flag.

lsp¶

--> lsp [-h]

Show the configured profiles.

optional arguments:
  -h, --help  show this help message and exit

New in version 0.1.8.

profile¶

--> profile [-h]

Edit the configuration file(s).

optional arguments:
  -h, --help  show this help message and exit

This will start `vi` with the selected config file.

New in version 1.2.3.

progress¶

--> progress [-h]

Toggle showing a progressmeter on/off.

optional arguments:
  -h, --help  show this help message and exit

New in version 1.2.1.

put¶

--> put [-h] [-m] sourcefile targetobject [meta ...]

Put (upload) "sourcefile" as "targetobject" into the attached bucket, adding metadata pairs if specified.

positional arguments:
  sourcefile    name of the local (source) file to upload.
  targetobject  name of the object in the target bucket.
  meta          format is: "key:value"

optional arguments:
  -h, --help    show this help message and exit
  -m            do a multi-part upload, if ever possible.

Changed in version 0.1.12: added multipart upload

quit¶

--> quit [-h]

Exit hs3sh gracefully.

optional arguments:
  -h, --help  show this help message and exit

rm¶

--> rm [-h] object [version_id]

Delete object from the attached bucket.

positional arguments:
  object      name of the object to remove.
  version_id  id of the object version to remove

optional arguments:
  -h, --help  show this help message and exit

run¶

--> run [-h] commandfile

Run a batch of commands stored in commandfile. A commandfile is just a plain sequential list of commands to be run, as you would enter them intoan interactive session.
Not ending it with "bye" will leavethe interactive session open.

positional arguments:
  commandfile  name of the commandfile to run.

optional arguments:
  -h, --help   show this help message and exit

New in version 0.1.15.

status¶

--> status [-h]

Show the session status (the connected endpoint and the attached bucket).

optional arguments:
  -h, --help  show this help message and exit

Changed in version 0.1.5: Adopted to work with profiles.

time¶

--> time [-h] command [args ...]

Measure the time command takes to complete.

positional arguments:
  command     the command to run
  args        (optional) arguments

optional arguments:
  -h, --help  show this help message and exit

New in version 0.1.5.

url¶

--> url [-h] [-m MINUTES] [-u] object

Generate a pre-signed URL to access an object.

positional arguments:
  object      the object name (key)

optional arguments:
  -h, --help  show this help message and exit
  -m MINUTES  set the expiration time for the URL to MINUTES (defaults to 60 minutes)
  -u          generates an upload URL instead of a download URL

New in version 0.1.12.