IBM Cloud Docs
IBM Cloud Object Storage CLI

IBM Cloud Object Storage CLI

The IBM Cloud® Object Storage plug-in extends the IBM Cloud command line interface (CLI) with an API wrapper for working with object storage resources.

Installation and configuration

The plugin is compatible with Linux (x86_64, arm64, ppc64le, s390x), Windows (x64), and macOS (amd64, arm64) platforms that run on 64-bit processors.

Install the plug-in by using the plugin install command.

ibmcloud plugin install cloud-object-storage

Once the plug-in is installed, you can configure the plug-in by using the ibmcloud cos config command. This can be used to populate the plug-in with your credentials, default download location, choosing your authentication, and so on.

For optimal performance, ensure that tracing is disabled by setting the IBMCLOUD_TRACE environment variable to false.

The program also offers the ability for you to set the default local directory for downloaded files, and to set a default region. To set the default download location, type ibmcloud cos config ddl and input into the program a valid file path. To set a default region, type ibmcloud cos config region and provide an input into the program a region code, such as us-south. By default, this value is set to us-geo.

You can view your current IBM Cloud Object Storage credentials by prompting ibmcloud cos config list. As the config file is generated by the plug-in, it's best not to edit the file manually.

$ ibmcloud cos config list
Key                     Value
Last Updated            Tuesday, April 28 2020 at 19:35:57
Default Region          us-south
Download Location       /home/ibmuser/Downloads
CRN                     8f275e7b-c076-49e2-b9c5-f985704cf678
AccessKeyID             9eib1eejar6HaezaohveV5hikei4aNg2ooV0qu
SecretAccessKey         ********************************************
Authentication Method   IAM
URL Style               VHost

IAM Authentication

If you are using IAM authentication, then you then you must configure your client with an instance ID to use some of the commands. To retrieve the instance ID you can type ibmcloud resource service-instance <INSTANCE_NAME> --id, replace <INSTANCE_NAME> with the unique alias that you assigned to your service instance. In the below examples, the 8f275e7b-c076-49e2-b9c5-f985704cf678 value is an example instance ID.

First, retrieve the CRN and id with the name of your instance. Be sure to use quotes (') on your instance name and that you are logged in to IBM Cloud. Only the last piece of the CRN is needed, the part after ::.

$ ibmcloud resource service-instance 'My Awesome Cloud Object Storage'  --id
Retrieving service instance My Awesome Cloud Object Storage in all resource groups under account IBM as ibmuser@us.ibm.com...
crn:v1:bluemix:public:cloud-object-storage:global:a/94400e98c553415c9599db39b9be9219:3b7d66c8-9fdf-4f81-b7e6-08d187f07288:: 8f275e7b-c076-49e2-b9c5-f985704cf678

Set the CRN with the ibmcloud cos config crn command. It may warn you about overwriting. If you don't want to provide the CRN interactively, you can provide it on the same command with the --crn flag.

$ ibmcloud cos config crn
Resource Instance ID CRN:  ()> 8f275e7b-c076-49e2-b9c5-f985704cf678
Saving new Service Instance ID...
OK
Successfully stored your service instance ID.

Verify the configuration:

$ ibmcloud cos config crn --list
Key   Value
CRN   8f275e7b-c076-49e2-b9c5-f985704cf678

Alternatively, you might open the web-based console, select Service credentials in the sidebar, and create a new set of credentials (or view an existing credential file that you already created).

HMAC Credentials

If preferred, a Service ID's HMAC credentials can be used instead of your API key. Run ibmcloud cos config hmac to input the HMAC credentials, and then switch the authorization method by using ibmcloud cos config auth.

If you choose to use token authentication with your own API key, you don't need to provide any credentials as the program authenticates you automatically.

At any time, to switch between HMAC and IAM authentication, you can type ibmcloud cos config auth. For more information about authentication and authorization in IBM Cloud, see the Identity and Access Management documentation.

Enable tracing in the command line interface

Tracing can be enabled by setting IBMCLOUD_TRACE environment variable to true (case ignored). When trace is enabled, additional debugging information is printed to the terminal.

On Linux/macOS terminal:

export IBMCLOUD_TRACE=true

On Windows prompt:

SET IBMCLOUD_TRACE=true

To disable tracing, set the IBMCLOUD_TRACE environment variable to false (case ignored).

Command index

Each operation has an explanation of what it does, how to use it, and any optional or required parameters. Unless specified as optional, any listed parameters are mandatory.

The CLI plug-in doesn't yet support the full suite of features available in Object Storage. Aspera High-Speed Transfer, Immutable Object Storage, creating Key Protect buckets, or Bucket Firewalls cannot be used by the CLI.

Abort a multipart upload

  • Action: Abort a multipart upload instance by ending the upload to the bucket in the user's IBM Cloud Object Storage account.
  • Usage: ibmcloud cos multipart-upload-abort --bucket BUCKET_NAME --key KEY --upload-id ID [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • The KEY of the object.
      • Flag: --key KEY
    • Upload ID identifying the multipart upload.
      • Flag: --upload-id ID
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Configure a static website

  • Action: Configures a bucket to host a static website.

  • Usage: ibmcloud cos bucket-website-put --bucket BUCKET_NAME [--region REGION] [--output FORMAT]

  • Parameters to provide:

    • The name of the bucket. =======

    • Flag: --bucket BUCKET_NAME

    • The website configuration in the form of a JSON structure. The file:// prefix is used to load the JSON structure from the specified file, such as --website-configuration file://<filename.json>.

    • Flag: --website-configuration STRUCTURE The following parameters are available for configuring static website behavior. None are required. For more details, see the documentation.

      {
        "ErrorDocument": {
          "Key": "string"
        },
        "IndexDocument": {
          "Suffix": "string"
        },
        "RoutingRules": [
          {
            "Condition": {
              "HttpErrorCodeReturnedEquals": "string",
              "KeyPrefixEquals": "string"
            },
            "Redirect": {
              "HostName": "string",
              "HttpRedirectCode": "string",
              "Protocol": "http"|"https",
              "ReplaceKeyPrefixWith": "string",
              "ReplaceKeyWith": "string"
            }
          }
          ...
        ]
      }
      

      Alternatively, if the bucket website is configured to redirect traffic, it must be the only parameter configured:

        "RedirectAllRequestsTo": {
          "HostName": "string",
          "Protocol": "http"|"https"
        }
        ```
      
      
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.

    • Flag: --region REGION

    • Optional: Output FORMAT can be only json or text.

    • Flag: --output FORMAT

Copy object from bucket

If you want to add metadata to an object during the copying (using the --metadata feature), you must add the attribute --metadata-directive REPLACE as metadata is copied during the operation by default (an implicit --metadata-directive COPY).

  • Action: Copy an object from source bucket to destination bucket.
  • Usage: ibmcloud cos object-copy --bucket BUCKET_NAME --key KEY --copy-source SOURCE [--cache-control CACHING_DIRECTIVES] [--content-disposition DIRECTIVES] [--content-encoding CONTENT_ENCODING] [--content-language LANGUAGE] [--content-type MIME] [--copy-source-if-match ETAG] [--copy-source-if-modified-since TIMESTAMP] [--copy-source-if-none-match ETAG] [--copy-source-if-unmodified-since TIMESTAMP] [--metadata MAP] [--metadata-directive DIRECTIVE] [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the destination bucket.
    • Flag: --bucket BUCKET_NAME
    • The KEY of the object.
    • Flag: --key KEY
    • (SOURCE) The name of the source bucket and key name of the source object, which is separated by a slash (/). Must be URL-encoded.
    • Flag: --copy-source SOURCE
    • Optional: Specifies CACHING_DIRECTIVES for the request and reply chain.
    • Flag: --cache-control CACHING_DIRECTIVES
    • Optional: Specifies presentation information (DIRECTIVES).
    • Flag: --content-disposition DIRECTIVES
    • Optional: Specifies what content encodings (CONTENT_ENCODING) are applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
    • Flag: --content-encoding CONTENT_ENCODING
    • Optional: The LANGUAGE the content is in.
    • Flag: --content-language LANGUAGE
    • Optional: A standard MIME type describing the format of the object data.
    • Flag: --content-type MIME
    • Optional: Copies the object if its entity tag (Etag) matches the specified tag (ETAG).
    • Flag: --copy-source-if-match ETAG
    • Optional: Copies the object if it has been modified since the specified time (TIMESTAMP).
    • Flag: --copy-source-if-modified-since TIMESTAMP
    • Optional: Copies the object if its entity tag (ETag) is different than the specified tag (ETAG).
    • Flag: --copy-source-if-none-match ETAG
    • Optional: Copies the object if it hasn't been modified since the specified time (TIMESTAMP).
    • Flag: --copy-source-if-unmodified-since TIMESTAMP
    • Optional: A MAP of metadata to store.
    • Flag: --metadata MAP JSON Syntax: The --metadata flag takes the file:// prefix that is used to load the JSON structure from the specified file.
      {
        "file_name": "file_20xxxxxxxxxxxx45.zip",
        "label": "texas",
        "state": "Texas",
        "Date_to": "2019-11-09T16:00:00.000Z",
        "Sha256sum": "9e39dxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8ce6b68ede3a47",
        "Timestamp": "Thu, 17 Oct 2019 09:22:13 GMT"
      }
      ```

   * _Optional_: Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request. DIRECTIVE values: COPY,REPLACE.
        * Flag: ` --metadata-directive DIRECTIVE`
    * _Optional_: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
        * Flag: `--region REGION`
    * _Optional_: Output FORMAT can be only json or text.
        * Flag: `--output FORMAT`

Create a new bucket

  • Action: Create a bucket in an IBM Cloud Object Storage instance.
  • Usage: ibmcloud cos bucket-create --bucket BUCKET_NAME [--class CLASS_NAME][--class onerate_active] [--ibm-service-instance-id ID] [--region REGION] [--output FORMAT]
    • Note that you must provide a CRN if you are using IAM authentication. This can be set by using the ibmcloud cos config crn command.
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • Optional: The name of the Class.
      • Flag: --class CLASS_NAME
    • User must specify onerate_active when creating a bucket.
      • Flag: --class onerate_active
    • Optional: Sets the IBM Service Instance ID in the request.
      • Flag: --ibm-service-instance-id ID
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Create a new bucket with Key Protect

  • Action: Create a bucket with Key Protect in an IBM Cloud Object Storage instance.
  • Usage: bucket-create --bucket BUCKET_NAME [--ibm-service-instance-id ID] [--class CLASS_NAME] [--region REGION] --kms-root-key-crn CUSTOMERROOTKEYCRN --kms-encryption-algorithm ALGORITHM [--output FORMAT] [--json]
    • Note that you must provide a CRN if you are using IAM authentication. This can be set by using the ibmcloud cos config crn command.
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • The CUSTOMERROOTKEYCRN of the KMS root key to be associated with the bucket for data encryption.
      • Flag: --kms-root-key-crn CUSTOMERROOTKEYCRN
    • Optional: The ALGORITHM and SIZE to use with the encryption key stored by using key protect.
      • Flag: --kms-encryption-algorithm ALGORITHM
    • Optional: The name of the Class.
      • Flag: --class CLASS_NAME
    • Optional: Sets the IBM Service Instance ID in the request.
      • Flag: --ibm-service-instance-id ID
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT
    • (Deprecated): Output returned in raw JSON format..
      • Flag: --json

Example:

ibmcloud cos bucket-create --bucket bucket-name --kms-root-key-crn crn:v1:staging:public:kms:us-south:a/9978e0xxxxxxxxxxxxxxxxxxxxxx8654:dfdxxxxx-xxxx-xxxx-xxxx-xxxxxxba6eb0:key:7cea005e-75d4-4a08-ad2f-5e56141f6a96 --kms-encryption-algorithm AES256

Create a new bucket with Hyper Protect Crypto Services

  • Action: Create a new bucket with Hyper Protect Crypto Services.
  • Usage: bucket-create --bucket BUCKET_NAME [--ibm-service-instance-id ID] [--class CLASS_NAME] [--region REGION] --kms-root-key-crn CUSTOMERROOTKEYCRN --kms-encryption-algorithm ALGORITHM [--output FORMAT] [--json]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • The CUSTOMERROOTKEYCRN of the KMS root key to be associated with the bucket for data encryption.
      • Flag: --kms-root-key-crn CUSTOMERROOTKEYCRN
    • Optional: The ALGORITHM and SIZE to use with the encryption key stored by using key protect.
      • Flag: --kms-encryption-algorithm ALGORITHM
    • Optional: The name of the Class.
      • Flag: --class CLASS_NAME
    • Optional: Sets the IBM Service Instance ID in the request.
      • Flag: --ibm-service-instance-id ID
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT
    • (Deprecated): Output returned in raw JSON format..
      • Flag: --json

Example:

ibmcloud cos bucket-create --bucket bucket-name --kms-root-key-crn crn:v1:bluemix:public:hs-crypto:us-south:a/ee747e4xxxxxxxxxxxxxxxxxxxxxx7559:ac6xxxxx-xxxx-xxxx-xxxx-xxxxxx1bea99:key:e7451f36-d7ea-4f55-bc1c-ce4bcceb7018

Create a new multipart upload

  • Action: Begin the multipart file upload process by creating a new multipart upload instance.

  • Usage: ibmcloud cos multipart-upload-create --bucket BUCKET_NAME --key KEY [--cache-control CACHING_DIRECTIVES] [--content-disposition DIRECTIVES] [--content-encoding CONTENT_ENCODING] [--content-language LANGUAGE] [--content-type MIME] [--metadata MAP] [--region REGION] [--output FORMAT]

  • Parameters to provide:

    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • The KEY of the object.
      • Flag: --key KEY
    • Optional: Specifies CACHING_DIRECTIVES for the request and reply chain.
      • Flag: --cache-control CACHING_DIRECTIVES
    • Optional: Specifies presentation information (DIRECTIVES).
      • Flag: --content-disposition DIRECTIVES
    • Optional: Specifies the content encoding (CONTENT_ENCODING) of the object..
      • Flag: --content-encoding CONTENT_ENCODING
    • Optional: The LANGUAGE the content is in.
      • Flag: --content-language LANGUAGE
    • Optional: A standard MIME type describing the format of the object data.
      • Flag: --content-type MIME
    • Optional: A MAP of metadata to store.
      • Flag: --metadata MAP JSON Syntax: The --metadata flag takes the file:// prefix that is used to load the JSON structure from the specified file.
    {
      "file_name": "file_20xxxxxxxxxxxx45.zip",
      "label": "texas",
      "state": "Texas",
      "Date_to": "2019-11-09T16:00:00.000Z",
      "Sha256sum": "9e39dxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8ce6b68ede3a47",
      "Timestamp": "Thu, 17 Oct 2019 09:22:13 GMT"
    }
    
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Delete an existing bucket

  • Action: Delete an existing bucket in an IBM Cloud Object Storage instance.
  • Usage: ibmcloud cos bucket-delete --bucket BUCKET_NAME [--region REGION] [--force] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: The operation will do not ask for confirmation.
      • Flag: --force
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Delete bucket CORS

  • Action: Delete CORS configuration on a bucket in a user's IBM Cloud Object Storage account.
  • Usage: ibmcloud cos bucket-cors-delete --bucket BUCKET_NAME [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Delete a static website configuration

  • Action: Removes a bucket's static website configuration.
  • Usage: ibmcloud cos bucket-website-delete --bucket BUCKET_NAME [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket. =======
      • Flag: --bucket BUCKET_NAME
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Delete an object

  • Action: Delete an object from a bucket in a user's IBM Cloud Object Storage account.
  • Usage: ibmcloud cos object-delete --bucket BUCKET_NAME --key KEY [--region REGION] [--force] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • The KEY of the object.
      • Flag: --key KEY
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: The operation will do not ask for confirmation.
      • Flag: --force
      • Optional: Output FORMAT can be only json or text.
        • Flag: --output FORMAT

Delete multiple objects

  • Action: Delete multiple objects from a bucket in a user's IBM Cloud Object Storage account.

  • Usage: ibmcloud cos objects-delete --bucket BUCKET_NAME --delete STRUCTURE [--region REGION] [--output FORMAT]

  • Parameters to provide:

    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • A STRUCTURE using either shorthand or JSON syntax.
      • Flag: --delete STRUCTURE
      • Shorthand Syntax: --delete 'Objects=[{Key=string},{Key=string}],Quiet=boolean'
      • JSON Syntax: --delete file://<filename.json> ======= The --delete command takes a JSON structure listing the objects to delete. In this example, the file:// prefix is used to load the JSON structure from the specified file.
    {
    "Objects": [
    	{
    	"Key": "string",
    	"VersionId": "string"
    	}
    ...
    ],
    "Quiet": true|false
    }
    
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Download an object

  • Action: Download an object from a bucket in a user's IBM Cloud Object Storage account.
  • Usage: ibmcloud cos object-get --bucket BUCKET_NAME --key KEY [--if-match ETAG] [--if-modified-since TIMESTAMP] [--if-none-match ETAG] [--if-unmodified-since TIMESTAMP] [--range RANGE] [--response-cache-control HEADER] [--response-content-disposition HEADER] [--response-content-encoding HEADER] [--response-content-language HEADER] [--response-content-type HEADER] [--response-expires HEADER] [--region REGION] [--output FORMAT] [OUTFILE]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • The KEY of the object.
      • Flag: --key KEY
    • Optional: Return the object only if its entity tag (ETag) is the same as the ETAG specified, otherwise return a 412 (precondition failed).
      • Flag: --if-match ETAG
    • Optional: Return the object only if it has been modified since the specified TIMESTAMP, otherwise return a 304 (not modified).
      • Flag: --if-modified-since TIMESTAMP
    • Optional: Return the object only if its entity tag (ETag) is different from the ETAG specified, otherwise return a 304 (not modified).
      • Flag: --if-none-match ETAG
    • Optional: Return the object only if it has not been modified since the specified TIMESTAMP, otherwise return a 412 (precondition failed).
      • Flag: --if-unmodified-since TIMESTAMP
    • Optional: Downloads the specified RANGE bytes of an object.
      • Flag: --range RANGE
    • Optional: Sets the Cache-Control HEADER of the response.
      • Flag: --response-cache-control HEADER
    • Optional: Sets the Content-Disposition HEADER of the response.
      • Flag: --response-content-disposition HEADER
    • Optional: Sets the Content-Encoding HEADER of the response.
      • Flag: --response-content-encoding HEADER
    • Optional: Sets the Content-Language HEADER of the response.
      • Flag: --response-content-language HEADER
    • Optional: Sets the Content-Type HEADER of the response.
      • Flag: --response-content-type HEADER
    • Optional: Sets the Expires HEADER of the response.
      • Flag: --response-expires HEADER
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT
    • Optional: The location where to save the content of the object. If this parameter is not provided, the program uses the default location.
      • Parameter: OUTFILE

Download objects by using S3Manager

  • Action: Download objects from S3 concurrently.
  • Usage: ibmcloud cos download --bucket BUCKET_NAME --key KEY [--concurrency value] [--part-size SIZE] [--if-match ETAG] [--if-modified-since TIMESTAMP] [--if-none-match ETAG] [--if-unmodified-since TIMESTAMP] [--range RANGE] [--response-cache-control HEADER] [--response-content-disposition HEADER] [--response-content-encoding HEADER] [--response-content-language HEADER] [--response-content-type HEADER] [--response-expires HEADER] [--region REGION] [--output FORMAT] [OUTFILE]
  • Parameters to provide:
    • The name (BUCKET_NAME) of the bucket.
      • Flag: --bucket BUCKET_NAME
    • The KEY of the object.
      • Flag: --key KEY
    • Optional: The number of go routines to spin up in parallel per call to download when sending parts. Default value is 5.
      • Flag: --concurrency value
    • Optional: The buffer SIZE (in bytes) to use when buffering data into chunks and ending them as parts to S3. The minimum allowed part size is 5MB.
      • Flag: --part-size SIZE
    • Optional: Return the object only if its entity tag (ETag) is the same as the ETAG specified, otherwise return a 412 (precondition failed).
      • Flag: --if-match ETAG
    • Optional: Return the object only if it has been modified since the specified TIMESTAMP, otherwise return a 304 (not modified).
      • Flag: --if-modified-since TIMESTAMP
    • Optional: Return the object only if its entity tag(ETag) is different from the ETAG specified, otherwise return a 304 (not modified).
      • Flag: --if-none-match ETAG
    • Optional: Return the object only if it has not been modified since the specified TIMESTAMP, otherwise return a 412 (precondition failed).
      • Flag: --if-unmodified-since TIMESTAMP
    • Optional: Downloads the specified RANGE bytes of an object. For more information about the HTTP Range header, click here.
      • Flag: --range RANGE
    • Optional: Sets the Cache-Control HEADER of the response.
      • Flag: --response-cache-control HEADER
    • Optional: Sets the Content-Disposition HEADER of the response.
      • Flag: --response-content-disposition HEADER
    • Optional: Sets the Content-Encoding HEADER of the response.
      • Flag: --response-content-encoding HEADER
    • Optional: Sets the Content-Language HEADER of the response.
      • Flag: --response-content-language HEADER
    • Optional: Sets the Content-Type HEADER of the response.
      • Flag: --response-content-type HEADER
    • Optional: Sets the Expires HEADER of the response.
      • Flag: --response-expires HEADER
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program will use the default option specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT
    • Optional: The location where to save the content of the object. If this parameter is not provided, the program uses the default location.
      • Parameter: OUTFILE

Find a bucket

  • Action: Determine the region and class of a bucket in an IBM Cloud Object Storage instance.
  • Usage: ibmcloud cos bucket-location-get --bucket BUCKET_NAME [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Get a bucket's class

  • Action: Determine the class of a bucket in an IBM Cloud Object Storage instance.
  • Usage: ibmcloud cos bucket-class-get --bucket BUCKET_NAME [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Get bucket CORS

  • Action: Returns the CORS configuration for the bucket in a user's IBM Cloud Object Storage account.
  • Usage: ibmcloud cos bucket-cors-get --bucket BUCKET_NAME [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Get a bucket's headers

  • Action: Determine if a bucket exists in an IBM Cloud Object Storage instance.
  • Usage: ibmcloud cos bucket-head --bucket BUCKET_NAME [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Complete a multipart upload

  • Action: Complete a multipart upload instance by assembling the currently uploaded parts and uploading the file to the bucket in the user's IBM Cloud Object Storage account.
  • Usage: ibmcloud cos multipart-upload-complete --bucket BUCKET_NAME --key KEY --upload-id ID --multipart-upload STRUCTURE [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.

      • Flag: --bucket BUCKET_NAME
    • The KEY of the object.

      • Flag: --key KEY
    • Upload ID identifying the multipart upload.

      • Flag: --upload-id ID
    • The STRUCTURE of MultipartUpload to set.

      • Flag: --multipart-upload STRUCTURE
      • Shorthand Syntax: --multipart-upload 'Parts=[{ETag=string,PartNumber=integer},{ETag=string,PartNumber=integer}]'
      • JSON Syntax: --multipart-upload file://<filename.json> ======= The --multipart-upload command takes a JSON structure that describes the parts of the multipart upload that should be reassembled into the complete file. In this example, the file:// prefix is used to load the JSON structure from the specified file.
      	{
      	"Parts": [
      		{
      		 "ETag": "string",
      		 "PartNumber": integer
      		}
      		...
      		]
      	}
      
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.

      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.

      • Flag: --output FORMAT

Configure the Program

  • Action: Configure the program's preferences.
  • Usage: ibmcloud cos config [COMMAND]
  • Commands:
    • Switch between HMAC and IAM authentication.
      • Command: auth
    • Store CRN in the config.
      • Command: crn
    • Store Default Download Location in the config.
      • Command: ddl
    • Store HMAC credentials in the config.
      • Command: hmac
    • List configuration.
      • Command: list
    • Store Default Region in the config.
      • Command: region
    • Switch between VHost and Path URL style.
      • Command: url-style
    • Set Default Service Endpoint.
      • Command: endpoint-url
        • Parameters: =======
          • --list displays the current default Service Endpoint, if it has been set. Otherwise, it will be empty.
          • --url some.end.point.url will change the Service Endpoint to the value as given.
          • --clear removes the default Service Endpoint URL that has been set.

Get a static website configuration

  • Action: Gets a bucket's static website configuration.
  • Usage: ibmcloud cos bucket-website-get --bucket BUCKET_NAME [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket. =======
      • Flag: --bucket BUCKET_NAME
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Get an object's headers

  • Action: Determine if a file exists in a bucket in a user's IBM Cloud Object Storage account.
  • Usage: ibmcloud cos object-head --bucket BUCKET_NAME --key KEY [--if-match ETAG] [--if-modified-since TIMESTAMP] [--if-none-match ETAG] [--if-unmodified-since TIMESTAMP] [--range RANGE] [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • The KEY of the object.
      • Flag: --key KEY
    • Optional: Return the object only if its entity tag (ETag) is the same as the ETAG specified, otherwise return a 412 (precondition failed).
      • Flag: --if-match ETAG
    • Optional: Return the object only if it has been modified since the specified TIMESTAMP, otherwise return a 304 (not modified).
      • Flag: --if-modified-since TIMESTAMP
    • Optional: Return the object only if its entity tag (ETag) is different from the ETAG specified, otherwise return a 304 (not modified).
      • Flag: --if-none-match ETAG
    • Optional: Return the object only if it has not been modified since the specified TIMESTAMP, otherwise return a 412 (precondition failed).
      • Flag: --if-unmodified-since TIMESTAMP
    • Downloads the specified RANGE bytes of an object.
      • Flag: --range RANGE
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

List all buckets

  • Action: Print a list of all the buckets in a user's IBM Cloud Object Storage account. Buckets might be located in different regions.
  • Usage: ibmcloud cos buckets [--ibm-service-instance-id ID] [--output FORMAT]
    • Note that you must provide a CRN if you are using IAM authentication. This can be set by using the ibmcloud cos config crn command.
  • Parameters to provide:
    • No parameters to provide.
      • Optional: Sets the IBM Service Instance ID in the request.
        • Flag: --ibm-service-instance-id
      • Optional: Output FORMAT can be only json or text.
        • Flag: --output FORMAT

Extended Bucket Listing

  • Action: Print a list of all the buckets in a user's IBM Cloud Object Storage account. Buckets might be located in different regions.
  • Usage: ibmcloud cos buckets-extended [--ibm-service-instance-id ID] [--marker KEY] [--prefix PREFIX] [--page-size SIZE] [--max-items NUMBER] [--output FORMAT]
    • Note that you must provide a CRN if you are using IAM authentication. This can be set by using the ibmcloud cos config crn command.
  • Parameters to provide:
    • No parameters to provide.
      • Optional: Sets the IBM Service Instance ID in the request.
        • Flag: --ibm-service-instance-id
      • Optional: Specifies the KEY to start with when listing objects in a bucket.
        • Flag: --marker KEY
      • Optional: Limits the response to keys that begin with the specified PREFIX.
        • Flag: --prefix PREFIX
      • Optional: The SIZE of each page to get in the service call. This does not affect the number of items returned in the command's output. Setting a smaller page size results in more calls to the service, retrieving fewer items in each call. This can help prevent the service calls from timing out.
        • Flag: --page-size SIZE
      • Optional: The total NUMBER of items to return in the command's output.
        • Flag: --max-items NUMBER
      • Optional: Output FORMAT can be only json or text.
        • Flag: --output FORMAT

List in-progress multipart uploads

  • Action: Lists in-progress multipart uploads.
  • Usage: ibmcloud cos multipart-uploads --bucket BUCKET_NAME [--delimiter DELIMITER] [--encoding-type METHOD] [--prefix PREFIX] [--key-marker value] [--upload-id-marker value] [--page-size SIZE] [--max-items NUMBER] [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • Optional: A DELIMITER is a character that you use to group keys.
      • Flag: --delimiter DELIMITER
    • Optional: Requests to encode the object keys in the response and specifies the encoding METHOD to use.
      • Flag: --encoding-type METHOD
    • Optional: Limits the response to keys that begin with the specified PREFIX.
      • Flag: --prefix PREFIX
    • Optional: Together with upload-id-marker, this parameter specifies the multipart upload after which listing should begin.
      • Flag: --key-marker value
    • Optional: Together with key-marker, specifies the multipart upload after which listing should begin. If key-marker is not specified, the upload-id-marker parameter is ignored.
      • Flag: --upload-id-marker value
    • Optional: The SIZE of each page to get in the service call. This does not affect the number of items returned in the command's output. Setting a smaller page size results in more calls to the service, retrieving fewer items in each call. This can help prevent the service calls from timing out. (default: 1000).
      • Flag: --page-size SIZE
    • Optional: The total NUMBER of items to return in the command's output. If the total number of items available is more than the value specified, a NextToken is provided in the command's output. To resume pagination, provide the NextToken value in the starting-token argument of a subsequent command. (default: 0).
      • Flag: --max-items NUMBER
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

List objects

  • Action: List files present in a bucket in a user's IBM Cloud Object Storage Account. This operation is currently limited to the 1000 most recently created objects and can't be filtered.
  • Usage: ibmcloud cos objects --bucket BUCKET_NAME [--delimiter DELIMITER] [--encoding-type METHOD] [--prefix PREFIX] [--starting-token TOKEN] [--page-size SIZE] [--max-items NUMBER] [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • Optional: A DELIMITER is a character that you use to group keys.
      • Flag: --delimiter DELIMITER
    • Optional: Requests to encode the object keys in the response and specifies the encoding METHOD to use.
      • Flag: --encoding-type METHOD
    • Optional: Limits the response to keys that begin with the specified PREFIX.
      • Flag: --prefix PREFIX
    • Optional: A TOKEN to specify where to start paginating. This is the NextToken from a previously truncated response.
      • Flag: --starting-token TOKEN
    • Optional: The SIZE of each page to get in the service call. This does not affect the number of items returned in the command's output. Setting a smaller page size results in more calls to the service, retrieving fewer items in each call. This can help prevent the service calls from timing out. (default: 1000)
      • Flag: --page-size SIZE
    • Optional: The total NUMBER of items to return in the command's output. If the total number of items available is more than the value specified, a NextToken is provided in the command's output. To resume pagination, provide the NextToken value in the starting-token argument of a subsequent command. (default: 0)
      • Flag: --max-items NUMBER
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

List objects v2

  • Action: List all objects in a specific bucket.
  • Usage: list-objects-v2 --bucket BUCKET_NAME [--starting-token Starting Token] [--delimiter DELIMITER] [--encoding-type METHOD] [--fetch-owner Boolean] [--max-items NUMBER] [--prefix PREFIX] [--start-after Start After] [--page-size SIZE] [--region REGION] [--output FORMAT] [--json]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • Optional: A DELIMITER is a character that you use to group keys.
      • Flag: --delimiter DELIMITER
    • Optional: Requests to encode the object keys in the response and specifies the encoding METHOD to use.
      • Flag: --encoding-type METHOD
    • Optional: Limits the response to keys that begin with the specified PREFIX.
      • Flag: --prefix PREFIX
    • Optional: A TOKEN to specify where to start paginating. This is the NextToken from a previously truncated response.
      • Flag: --starting-token TOKEN
    • Optional: The SIZE of each page to get in the service call. This does not affect the number of items returned in the command's output. Setting a smaller page size results in more calls to the service, retrieving fewer items in each call. This can help prevent the service calls from timing out. (default: 1000)
      • Flag: --page-size SIZE
    • Optional: The total NUMBER of items to return in the command's output. If the total number of items available is more than the value specified, a NextToken is provided in the command's output. To resume pagination, provide the NextToken value in the starting-token argument of a subsequent command. (default: 0)
      • Flag: --max-items NUMBER
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT
    • Optional: The Boolean is not present in listV2 by default, if you want to return owner field with each key in the result then set the fetch owner field to true.
      • Flag: --fetch-owner Boolean
    • Optional: Start After is where you want S3 to start listing from. S3 starts listing after this specified key. StartAfter can be any key in the bucket.
      • Flag: --start-after Start After
    • Deprecated: Output returned in raw JSON format.
      • Flag: --json

List parts

  • Action: Print out information about an in progress multipart upload instance.
  • Usage: ibmcloud cos parts --bucket BUCKET_NAME --key KEY --upload-id ID --part-number-marker VALUE [--page-size SIZE] [--max-items NUMBER] [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • The KEY of the object.
      • Flag: --key KEY
    • Upload ID identifying the multipart upload.
      • Flag: --upload-id ID
    • Part number VALUE after which listing begins (default: 1)
      • Flag: --part-number-marker VALUE
    • Optional: The SIZE of each page to get in the service call. This does not affect the number of items returned in the command's output. Setting a smaller page size results in more calls to the service, retrieving fewer items in each call. This can help prevent the service calls from timing out. (default: 1000)
      • Flag: --page-size SIZE
    • Optional: The total NUMBER of items to return in the command's output. If the total number of items available is more than the value specified, a NextToken is provided in the command's output. To resume pagination, provide the NextToken value in the starting-token argument of a subsequent command. (default: 0)
      • Flag: --max-items NUMBER
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Set bucket CORS

  • Action: Sets the CORS configuration for a bucket in the user's IBM Cloud Object Storage account.

  • Usage: ibmcloud cos bucket-cors-put --bucket BUCKET_NAME [--cors-configuration STRUCTURE] [--region REGION] [--output FORMAT]

  • Parameters to provide:

    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • Optional: A STRUCTURE using JSON syntax in a file.
      • Flag: --cors-configuration STRUCTURE
      • JSON Syntax: --cors-configuration file://<filename.json> ======= The --cors-configuration command takes a JSON structure that describes the CORS configuration. In this example, the file:// prefix is used to load the JSON structure from the specified file.
    {
    "CORSRules": [
    	{
      	"AllowedHeaders": ["string", ...],
      	"AllowedMethods": ["string", ...],
      	"AllowedOrigins": ["string", ...],
      	"ExposeHeaders": ["string", ...],
      	"MaxAgeSeconds": integer
    	}
    	...
    ]
    }
    
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Put object

  • Action: Upload an object to a bucket in a user's IBM Cloud Object Storage account.

  • Usage: ibmcloud cos object-put --bucket BUCKET_NAME --key KEY [--body FILE_PATH] [--cache-control CACHING_DIRECTIVES] [--content-disposition DIRECTIVES] [--content-encoding CONTENT_ENCODING] [--content-language LANGUAGE] [--content-length SIZE] [--content-md5 MD5] [--content-type MIME] [--metadata MAP] [--region REGION] [--output FORMAT]

  • Parameters to provide:

    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • The KEY of the object.
      • Flag: --key KEY
    • Optional: Object data location (FILE_PATH).
      • Flag: --body FILE_PATH
    • Optional: Specifies CACHING_DIRECTIVES for the request and reply chain.
      • Flag: --cache-control CACHING_DIRECTIVES
    • Optional: Specifies presentation information (DIRECTIVES).
      • Flag: --content-disposition DIRECTIVES
    • Optional: Specifies the content encoding (CONTENT_ENCODING) of the object.
      • Flag: --content-encoding CONTENT_ENCODING
    • Optional: The LANGUAGE the content is in.
      • Flag: --content-language LANGUAGE
    • Optional: SIZE of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically. (default: 0)
      • Flag: --content-length SIZE
    • Optional: The base64-encoded 128-bit MD5 digest of the data.
      • Flag: --content-md5 MD5
    • Optional: A standard MIME type describing the format of the object data.
      • Flag: --content-type MIME
    • Optional: A MAP of metadata to store.
      • Flag: --metadata MAP JSON Syntax: The --metadata flag takes the file:// prefix that is used to load the JSON structure from the specified file.
    {
      "file_name": "file_20xxxxxxxxxxxx45.zip",
      "label": "texas",
      "state": "Texas",
      "Date_to": "2019-11-09T16:00:00.000Z",
      "Sha256sum": "9e39dxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8ce6b68ede3a47",
      "Timestamp": "Thu, 17 Oct 2019 09:22:13 GMT"
    }
    
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Upload objects by using S3Manager

  • Action: Upload objects to COS concurrently.

  • Usage: ibmcloud cos upload --bucket BUCKET_NAME --key KEY --file PATH [--concurrency value] [--max-upload-parts PARTS] [--part-size SIZE] [--leave-parts-on-errors] [--cache-control CACHING_DIRECTIVES] [--content-disposition DIRECTIVES] [--content-encoding CONTENT_ENCODING] [--content-language LANGUAGE] [--content-length SIZE] [--content-md5 MD5] [--content-type MIME] [--metadata MAP] [--region REGION] [--output FORMAT]

  • Parameters to provide:

    • The name (BUCKET_NAME) of the bucket.
      • Flag: --bucket BUCKET_NAME
    • The KEY of the object.
      • Flag: --key KEY
    • The PATH to the file to upload.
      • Flag: --file PATH
    • Optional: The number of go routines to spin up in parallel per call to Upload when sending parts. Default value is 5.
      • Flag: --concurrency value
    • Optional: Max number of PARTS which will be uploaded to S3 that calculates the part size of the object to be uploaded. Limit is 10,000 parts.
      • Flag: --max-upload-parts PARTS
    • Optional: The buffer SIZE (in bytes) to use when buffering data into chunks and ending them as parts to S3. The minimum allowed part size is 5MB.
      • Flag: --part-size SIZE
    • Optional: Setting this value to true will cause the SDK to avoid calling AbortMultipartUpload on a failure, leaving all successfully uploaded parts on S3 for manual recovery.
      • Flag: --leave-parts-on-errors
    • Optional: Specifies CACHING_DIRECTIVES for the request/reply chain.
      • Flag: --cache-control CACHING_DIRECTIVES
    • Optional: Specifies presentational information (DIRECTIVES).
      • Flag: --content-disposition DIRECTIVES
    • Optional: Specifies what content encodings (CONTENT_ENCODING) have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
      • Flag: --content-encoding CONTENT_ENCODING
    • Optional: The LANGUAGE the content is in.
      • Flag: --content-language LANGUAGE
    • Optional: SIZE of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically.
      • Flag: --content-length SIZE
    • Optional: The base64-encoded 128-bit MD5 digest of the data.
      • Flag: --content-md5 MD5
    • Optional: A standard MIME type describing the format of the object data.
      • Flag: --content-type MIME
    • Optional: A MAP of metadata to store.
      • Flag: --metadata MAP JSON Syntax: The --metadata flag takes the file:// prefix that is used to load the JSON structure from the specified file.
    {
      "file_name": "file_20xxxxxxxxxxxx45.zip",
      "label": "texas",
      "state": "Texas",
      "Date_to": "2019-11-09T16:00:00.000Z",
      "Sha256sum": "9e39dxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8ce6b68ede3a47",
      "Timestamp": "Thu, 17 Oct 2019 09:22:13 GMT"
    }
    
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program will use the default option specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Manually controlling multipart uploads

The IBM Cloud Object Storage CLI provides the ability for users to upload large files in multiple parts by using the AWS multipart upload functions. To initiate a new multipart upload, run the multipart-upload-create command, which returns the new upload instance's upload ID. To continue with the upload process, you must save the upload ID for each subsequent command. This command requires you to generate an MD5 hash:

{object data} | openssl dgst -md5 -binary | openssl enc -base64

After running the multipart-upload-complete command, run part-upload for each file part you want to upload. For multipart uploads, every file part (except for the last part) must be at least 5 MB. To split a file into separate parts, you can run split in a terminal window. For example, if you have a 13 MB file that is named TESTFILE on your Desktop, and you would like to split it into file parts of 5 MB each, you can run split -b 3m ~/Desktop/TESTFILE part-file-. This command generates three file parts into two file parts of 5 MB each, and one file part of 3 MB, with the names part-file-aa, part-file-ab, and part-file-ac. As each file part is uploaded, the CLI print itsETag. You must save this ETaginto a formatted JSON file, along with the part number. Use this template to create your ownETag JSON data file.

{
    "Parts": [
    {
      "PartNumber": 1,
      "ETag": "The ETag of the first file part goes here."
    },
    {
      "PartNumber": 2,
      "ETag": "The ETag of the second file part goes here."
    }
    ]
}

Add more entries to this JSON template as necessary.

To see the status of your multipart upload instance, you can always run the part-list command, providing the bucket name, key, and the upload ID. This print raw information about your multipart upload instance. Once you have completed uploading each part of the file, run the multipart-upload-complete command with the necessary parameters. If all goes well, you receive a confirmation that the file uploaded successfully to the wanted bucket.

Upload a part

  • Action: Upload a part of a file in an existing multipart upload instance.
  • Usage: ibmcloud cos part-upload --bucket BUCKET_NAME --key KEY --upload-id ID --part-number NUMBER [--body FILE_PATH] [--region REGION] [--output FORMAT]
    • Note that you must save each uploaded file part's number and ETag (which the CLI will print for you) for each part into a JSON file. Refer to the "Multipart Upload Guide" below for more information.
  • Parameters to provide:
    • The bucket name where the multipart upload is taking place.
      • Flag: --bucket BUCKET_NAME
    • The KEY of the object.
      • Flag: --key KEY
    • Upload ID identifying the multipart upload.
      • Flag: --upload-id ID
    • Part NUMBER of part being uploaded. This is a positive integer in the range 1 - 10,000. (default: 1)
      • Flag: --part-number NUMBER
    • Optional: Object data location (FILE_PATH).
      • Flag: --body FILE_PATH
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Upload a part copy

  • Action: Upload a part by copying data from an existing object.
  • Usage: ibmcloud cos part-upload-copy --bucket BUCKET_NAME --key KEY --upload-id ID --part-number NUMBER --copy-source SOURCE [--copy-source-if-match ETAG] [--copy-source-if-modified-since TIMESTAMP] [--copy-source-if-none-match ETAG] [--copy-source-if-unmodified-since TIMESTAMP] [--copy-source-range value] [--region REGION] [--output FORMAT]
    • Note that you must save each uploaded file part's number and ETag (which the CLI will print for you) for each part into a JSON file. Refer to the "Multipart Upload Guide" for more information.
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • The KEY of the object.
      • Flag: --key KEY
    • Upload ID identifying the multipart upload.
      • Flag: --upload-id ID
    • Part NUMBER of part being uploaded. This is a positive integer between 1 and 10,000.
      • Flag: --part-number PART_NUMBER
    • (SOURCE) The name of the source bucket and key name of the source object, which is separated by a slash (/). Must be URL-encoded.
      • Flag: --copy-source SOURCE
    • Optional: Copies the object if its entity tag (Etag) matches the specified tag (ETAG).
      • Flag: --copy-source-if-match ETAG
    • Optional: Copies the object if it has been modified since the specified time (TIMESTAMP).
      • Flag: --copy-source-if-modified-since TIMESTAMP
    • Optional: Copies the object if its entity tag (ETag) is different than the specified tag (ETAG).
      • Flag: --copy-source-if-none-match ETAG
    • Optional: Copies the object if it hasn't been modified since the specified time (TIMESTAMP).
      • Flag: --copy-source-if-unmodified-since TIMESTAMP
    • Optional: The range of bytes to copy from the source object. The range value must use the form bytes=first-last, where the first and last are the zero-based byte offsets to copy. For example, bytes=0-9 indicates that you want to copy the first ten bytes of the source. You can copy a range only if the source object is greater than 5 MB.
      • Flag: --copy-source-range value
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Object Lock configuration

Put Object Lock configuration

In default retention Days and Years cannot be provided at the same time.

  • Action: Set the object lock configuration on a bucket.
  • Usage: object-lock-configuration-put --bucket BUCKET_NAME [--object-lock-configuration STRUCTURE] [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • A STRUCTURE using JSON syntax. See IBM Cloud Documentation.
      • Flag: --object-lock-configuration STRUCTURE

        {
        "ObjectLockEnabled": "Enabled",
        "Rule": {
        	"DefaultRetention": {
        	"Mode": "COMPLIANCE",
        	"Days": integer,
        	"Years": integer
        	}
        }
        }
        
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Example:

ibmcloud cos object-lock-configuration-put --bucket bucket-name --object-lock-configuration '{ "ObjectLockEnabled": "Enabled", "Rule": { "DefaultRetention": { "Mode": "COMPLIANCE", "Days": 30 }}}'

Get Object Lock configuration

  • Action: Get the object lock configuration on a bucket.
  • Usage: object-lock-configuration-get --bucket BUCKET_NAME [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • A STRUCTURE using JSON syntax. See IBM Cloud Documentation.
      • Flag: --object-lock-configuration STRUCTURE

        {
        "ObjectLockEnabled": "Enabled",
        "Rule": {
        	"DefaultRetention": {
        	"Mode": "COMPLIANCE",
        	"Days": integer,
        	"Years": integer
        	}
        }
        }
        
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

        {
        "ObjectLockEnabled": "Enabled",
        "Rule": {
        	"DefaultRetention": {
        	"Mode": "COMPLIANCE",
        	"Days": integer,
        	"Years": integer
        	}
        }
        }
        

Example:

ibmcloud cos object-lock-configuration-get --bucket bucket-name --region us-south

Object Retention

Put Object Retention

  • Action: Set retention on a object.
  • Usage: object-retention-put --bucket BUCKET_NAME --key KEY [--retention STRUCTURE] [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • The KEY of the object.
      • Flag: --key KEY
    • A STRUCTURE using JSON syntax. See IBM Cloud Documentation.
      • Flag: --retention STRUCTURE

        {
          "Mode": "COMPLIANCE",
          "RetainUntilDate": timestamp
        }
        
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Example:

ibmcloud cos object-retention-put --bucket bucket-name --key file-name.txt --retention '{ "Mode": "COMPLIANCE", "RetainUntilDate": "2024-02-02T00:00:00"}’

Get Object Retention

  • Action: Get retention on a object.
  • Usage: object-retention-get --bucket BUCKET_NAME --key KEY [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • The KEY of the object.
      • Flag: --key KEY
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

        {
        	"Retention": {
        		"Mode": "COMPLIANCE",
        		"RetainUntilDate": "2024-02-02T00:00:00.000Z"
        	}
        }
        

Example:

ibmcloud cos object-retention-put --bucket bucket-name --key file-name.txt --region us-south

Configure bucket replication

Setup for configuring a replicated bucket.

Put bucket replication

  • Action: Set the replication configuration on a bucket.
  • Usage: bucket-replication-put --bucket BUCKET_NAME [--replication-configuration STRUCTURE] [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

        {
        	"Rules": [
        		{
        			"Status": "Enabled",
        			"Priority": 1,
        			"Filter" : { "Prefix": ""},
        			"DeleteMarkerReplication": {
        				"Status": "Disabled"
        			},
        			"Destination": {
        				"Bucket": "DEST-BUCKET-NAME"
        			}
        		}
        	]
        }
        

Example:

ibmcloud cos bucket-replication-put --bucket SOURCE-BUCKET-NAME --replication-configuration file://replication.json

Get bucket replication

  • Action: Get the replication configuration for a bucket.
  • Usage: bucket-replication-get --bucket BUCKET_NAME [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

        {
        	"ReplicationConfiguration": {
        		"Rules": [
        			{
        				"Status": "Enabled",
        				"Prefix": "",
        				"Destination": {
        					"Bucket": "DEST-BUCKET-NAME",
        					"StorageClass": "STANDARD"
        				},
        			}
        		],
        	}
        }
        

Example:

 ibmcloud cos bucket-replication-get --bucket SOURCE-BUCKET-NAME

Delete bucket replication

  • Action: Delete the replication configuration from a bucket.
  • Usage: bucket-replication-delete --bucket BUCKET_NAME [--region REGION] [--output FORMAT]
  • Parameters to provide:
    • The name of the bucket.
      • Flag: --bucket BUCKET_NAME
    • Optional: The REGION where the bucket is present. If this flag is not provided, the program uses the default option that is specified in config.
      • Flag: --region REGION
    • Optional: Output FORMAT can be only json or text.
      • Flag: --output FORMAT

Example:

 ibmcloud cos bucket-replication-delete --bucket SOURCE-BUCKET-NAME

Next Steps

As every procedure always goes exactly as planned, you might not have seen any of the common header and error codes. For more reference, check the API reference.