Login and Switch Spaces With Bluemix CLI

After answering a bunch of questions about the Bluemix CLI tool for IBM Cloud, I thought I'd share my personal cheatsheet in case it helps anyone looking for examples!

Background: This relates to the Bluemix CLI for IBM Cloud (which was once called Bluemix, hence the tool name). IBM Cloud is a pretty powerful beast and so the related tools can sometimes be confusing, especially to newcomers. Here's my handy guide for working with it.

APIs and Regions

Before you log in, tell bx which region you want to log into by setting the API. When the region isn't set, the tool will often tell you No api endpoint set. Use 'bx api' to set an endpoint, so let's do that. If you don't have an API set, then the bx api command will show you a list of choices:

$ bx api
No api endpoint set. Use 'bx api' to set an endpoint

Available public api endpoints are:
Region     API Endpoint
eu-de      https://api.eu-de.bluemix.net
au-syd     https://api.au-syd.bluemix.net
us-south   https://api.ng.bluemix.net
eu-gb      https://api.eu-gb.bluemix.net

Set the API by using one of the URLs shown:

$ bx api https://api.eu-gb.bluemix.net
Setting api endpoint to https://api.eu-gb.bluemix.net...
OK

API endpoint: https://api.eu-gb.bluemix.net (CF API version: 2.92.0)
Not logged in. Use 'bx login' to log in.

However if the API is already set and you want to change it, the bx regions command will show that list again

$ bx regions
Listing Bluemix regions...

Name       Geolocation      Customer   Deployment   Domain               CF API Endpoint                  Type
eu-de      Germany          IBM        Production   eu-de.bluemix.net    https://api.eu-de.bluemix.net    public
au-syd     Sydney           IBM        Production   au-syd.bluemix.net   https://api.au-syd.bluemix.net   public
us-south   US South         IBM        Production   ng.bluemix.net       https://api.ng.bluemix.net       public
eu-gb      United Kingdom   IBM        Production   eu-gb.bluemix.net    https://api.eu-gb.bluemix.net    public

Now you can switch the API as before. If you work with IBM Cloud in multiple geographies, as I do (I'm in the UK but my team is in the US), you'll get to know this end of the tool very well indeed!

Logging In

Option 1: type bx login and you will be prompted for your login credentials (username/email, password). If you have access to more than one account then you'll be prompted to pick which one you need, or you can supply this information on the command line.

There's a bunch of other things that you might like to do with this command as well, such as:
* as I just mentioned: supply your Account ID with -c (more on accounts later)
* use an API Key rather than having to type your credentials (also more on this later)
* specify the organisation and space to target with -o and -s respectively (recommended)

If you use a federated login (IBM-ers, this includes you) then use bx login --sso instead. It will give you a URL to visit to get a one-time access code to log in with.

Targeting a Workspace

For some IBM Cloud features, you'll be in a particular workspace. This is a combination of region, account, organization and space and you can switch between these using the bx target command. Run it by itself to check where you're currently pointing to. You won't be able to see things in other spaces when you're not targeting that space.

Interactively choose target in this region/account this is helpful if you don't know exactly the words to type! bx target --cf presents a list of organizations and spaces in this current account/region for you to choose from. You can't script it but it's quite user-friendly!

Change regions with bx target -r eu-gb or whichever region you want. See the options with bx regions.

Change accounts with bx target -c [account ID], but get the account ID from the output of bx account list (look at the final section of this blog post for a helper script for this)

Change organizations and spaces with bx target -o [org] -s [space]. Find out the possibilities with bx account orgs and bx account spaces

Combine all of the above with bx -r eu-gb -c [accountID] --cf and get prompted for the organisation and space info, or replace --cf with -o and -s.

Generate an API Key

The access control features are a big topic but knowing how to create an API is useful here. You can give the token as a secret to your deployment script, or even set it in your environment so you can log in more easily. To generate an API key:

bx iam api-key-create

With the key then you can login with bx login --apikey [key].

Cloud Foundry Tools and The Bluemix CLI

Previously, IBM Cloud was accessed by the Cloud Foundry commandline tool, cf and I wrote a cheatsheet for that last year. If you're familiar with the cf tools then there are a few adjustments to make to your existing commands/scripts but it shouldn't be too weird:
* use bx instead of cf for these commands: login, logout, api, target
* for everything else, use bx cf instead of just cf

Some existing Cloud Foundry integrations will work if you supply a username of apikey and a valid API key as a password.

Lorna's Script Collection

Here's a quick dump of the helper scripts that I use to keep me moving quickly with IBM Cloud.

Federated User Login - I have one of these per region, with the API keys and one-time token URLs set as appropriate. You could probably use API keys here as well.

#!/bin/bash

bluemix logout
google-chrome https://iam.eu-gb.bluemix.net/identity/passcode
bluemix api https://api.eu-gb.bluemix.net
bluemix login --sso

This opens the token page in chrome (it's slow, so start this first!) so you can switch to and copy it, and sets the API, then starts the login process

Switching accounts - quick and dirty script, will basically pick the first account it finds that matches whatever argument you supplied. e.g. ./bxtarget.sh Lorna

#!/bin/bash

bx account list | tail -n +4 | grep -i $1 | cut -d ' ' -f 1 | xargs bx target -c

Do you have favourite tricks to share? I'd love to hear them!