IBM Cloud Object Storage CLI

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

$ 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

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

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

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

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

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

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

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

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.

Object Lock configuration

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

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

Object Retention

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

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

Object Legal Hold

ibmcloud cos object-legal-hold-put --bucket bucket-name --key file-name.txt --legal-hold ‘{"Status": "ON"}’

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

Configure bucket replication

Setup for configuring a replicated bucket.

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

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

 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.