IBM Cloud Object Storage CLI plug-in

This plug-in for the IBM Cloud CLI allows users to interact with IBM Cloud Object Storage services entirely from the command line.

Prerequisites

• An IBM Cloud account
• An instance of IBM Cloud Object Storage
• The IBM Cloud CLI

Install the plug-in

After you've installed ibmcloud, you need to install the plug-in.

1. Login to IBM Cloud (if you haven't already) with the command ibmcloud login.
2. Install the plug-in with ibmcloud plugin install cloud-object-storage.

Getting Started

You need to provide a Service Instance ID (CRN) for the IBM Cloud Object Storage instance you want to interact with by typing ibmcloud cos config crn. You can find the CRN with ibmcloud resource service-instance INSTANCE_NAME. 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).

Next, copy and paste the resource_instance_id from the credentials file into the CLI when it prompts you for a service instance ID. You can view your current Cloud Object Storage credentials by prompting ibmcloud cos config list. As the configuration file is generated by the plug-in, it's best not to edit the file manually.

Enter the following command to ensure the plug-in works for you:

ibmcloud cos -h

NAME:
   ibmcloud cos - Interact with IBM Cloud Object Storage services
USAGE:
   ibmcloud cos command [arguments...] [command options]

COMMANDS:
   multipart-upload-abort      Abort a multipart upload instance.
   multipart-upload-complete   Complete an existing multipart upload instance.
   config                      Changes plugin configuration
   object-copy                 Copy an object from one bucket to another.
   bucket-create               Create a new bucket.
   multipart-upload-create     Create a new multipart upload instance.
   bucket-delete               Delete an existing bucket.
   bucket-cors-delete          Delete the CORS configuration from a bucket.
   object-delete               Delete an object from a bucket.
   objects-delete              Delete multiple objects from a bucket
   download                    Download objects from S3 concurrently.
   get-bucket-class            Returns the class type of the specified bucket.
   bucket-cors-get             Get the CORS configuration from a bucket.
   bucket-location-get         Get the region and class of a bucket.
   object-get                  Download an object from a bucket.
   bucket-head                 Determine if a specified bucket exists in your account.
   object-head                 Determine if an object exists within a bucket.
   buckets                     List all the buckets in your IBM Cloud Object Storage account.
   list-buckets-extended       List all the extended buckets with pagination support.
   multipart-uploads           This operation lists in-progress multipart uploads.
   objects                     List all objects in a specific bucket.
   parts                       Display the list of uploaded parts of an object.
   bucket-cors-put             Set the CORS configuration on a bucket.
   object-put                  Upload an object to a bucket.
   upload                      Upload objects from S3 concurrently.
   part-upload                 Upload a part of an object.
   part-copy-upload            Upload a part by copying data from an existing object.
   wait                        Wait until a particular condition is satisfied.  Each subcommand polls an API until the listed requirement is met.
   help, h                     Show help

Enter 'ibmcloud cos help [command]' for more information about a command.

Example CLI usage

• Create a bucket in your IBM Cloud Object Storage account.

  • Usage: create-bucket --bucket BUCKET_NAME [--ibm-service-instance-id ID] [--class CLASS_NAME] [--region REGION]
    • EXAMPLE: ibmcloud cos create-bucket --bucket testcoscli --region us-south --class VAULT

• Put an object in an existing bucket.

  • Usage: put-object --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 STRUCTURE] [--region REGION]
    • EXAMPLE: ibmcloud cos put-object --bucket testcoscli --key cosfile --region us-south

• Delete an object in an existing bucket.

  • Usage: ibmcloud cos delete-object --bucket BUCKET_NAME --key KEY_NAME [--region REGION_NAME] [--force]
  • EXAMPLE: ibmcloud cos delete-object --bucket testcoscli --key cosfile --region us-south

For information on other commands, go to our plug-in page.

Build the plug-in from source

Building the IBM Cloud CLI COS plug-in requires the following utilities:

• The Go programming language
• make

First, you need to install Go.

To build and install the plug-in from source, run the four simple steps using Go modules:

git clone [email protected]:IBM/ibmcloud-cos-cli.git
cd ibmcloud-cos-cli
make
make install

NOTE: If you're refreshing the dependencies, use make clean option to remove the dependency files and then rebuild.

Getting Help

Feel free to use GitHub issues for tracking bugs and feature requests, but for help use one of the following resources:

• Read a quick start guide in IBM Docs.
• Ask a question on Stack Overflow and tag it with ibm and object-storage.
• Open a support ticket with IBM Cloud Support.
• If it turns out that you find a bug, open an issue.