/ibmcloud-cos-cli

Primary LanguageGo

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

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 config 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:
   abort-multipart-upload      Abort a multipart upload instance.
   complete-multipart-upload   Complete an existing multipart upload instance.
   config                      Changes plugin configuration
   copy-object                 Copy an object from one bucket to another.
   create-bucket               Create a new bucket.
   create-multipart-upload     Create a new multipart upload instance.
   delete-bucket               Delete an existing bucket.
   delete-bucket-cors          Delete the CORS configuration from a bucket.
   delete-object               Delete an object from a bucket.
   delete-objects              Delete multiple objects from a bucket
   download                    Download objects from S3 concurrently.
   get-bucket-class            Returns the class type of the specified bucket.
   get-bucket-cors             Get the CORS configuration from a bucket.
   get-bucket-location         Get the region and class of a bucket.
   get-object                  Download an object from a bucket.
   head-bucket                 Determine if a specified bucket exists in your account.
   head-object                 Determine if an object exists within a bucket.
   list-buckets                List all the buckets in your IBM Cloud Object Storage account.
   list-buckets-extended       List all the extended buckets with pagination support.
   list-multipart-uploads      This operation lists in-progress multipart uploads.
   list-objects                List all objects in a specific bucket.
   list-parts                  Display the list of uploaded parts of an object.
   put-bucket-cors             Set the CORS configuration on a bucket.
   put-object                  Upload an object to a bucket.
   upload                      Upload objects from S3 concurrently.
   upload-part                 Upload a part of an object.
   upload-part-copy            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 MAP] [--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:

First, you need to install Go.

Common practice is to set your GOPATH=$HOME/go. Update your ~/.bashrc, ~/.zshrc, or other run command file to set $GOPATH, $GOROOT, and $PATH.

export GOPATH=$HOME/go
export GOROOT=/usr/local/go
export PATH=$PATH:$GOPATH/bin:$GOROOT/bin

To build and install the plug-in from source, run the four simple steps under your $GOPATH:

git clone git@github.com:IBM/ibmcloud-cos-cli.git
cd ibmcloud-cos-cli
make
make install

NOTE: If you're refreshing the dependences, 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: