Technical Articles
SAP Tech Bytes: btp CLI – logging in
Start exploring with the btp CLI by logging in, then finding and selecting a subaccount for subsequent activities.
This is a follow-on post from the previous one: SAP Tech Bytes – btp CLI installation and assumes you’ve got it set up according to that post, in an SAP Business Application Studio (App Studio) dev space, with the location of the btp
binary (in $HOME/bin/
) added to the environment variable $PATH
so that you can invoke it simply as btp
.
Previously I made a brief mention of the client-server nature of the btp CLI. The fact that you’re running a command line interface to connect to and control remote services more or less pre-supposes that architecture; moreover, it’s a great way for the team to provide an abstraction between the btp CLI command structure and the surface area of the services & entities on the platform itself.
Invoking btp
Invoke btp
from a terminal in your App Studio dev space and stare at the output for a moment; it should look something like this:
Welcome to the SAP BTP command line interface (client v2.8.0)
Usage: btp [OPTIONS] ACTION [GROUP/OBJECT] [PARAMS]
CLI server URL: not set
User: not set
Configuration: /home/user/.cache/.btp/config.json
You are currently not logged in.
Tips:
To log in to a global account of SAP BTP, use 'btp login'. For help on login, use 'btp --help login'.
To display general help, use 'btp --help'.
OK
There’s a lot to unpack here. Briefly:
- the version of the client (that we downloaded last time) is confirmed as 2.8.0
- the “Usage” shows that there’s a well-defined structure to the command syntax
- we connect to a btp CLI server via a URL
- we’re not currently logged in
- configuration is stored locally in a JSON file
Logging in
Initiate the login process:
btp login
You should see the following prompts, and should respond similar to what’s shown here – see below for an explanation of the “Global account subdomain”:
SAP BTP command line interface (client v2.8.0)
CLI server URL [https://cpcli.cf.eu10.hana.ondemand.com]>
Connecting to CLI server at https://cpcli.cf.eu10.hana.ondemand.com...
Global account subdomain>82715b8dtrial-ga
User>sapdeveloper@example.com
Password>********
Login successful
We stored your configuration file at: /home/user/.cache/.btp/config.json
Current target:
Global account (subdomain: 82715b8dtrial-ga)
Tip:
For more information on the targeting mechanism, use 'btp --help target'.
OK
In the trial context, which we’re in here, the default CLI server that is suggested (https://cpcli.cf.eu10.hana.ondemand.com
) is appropriate.
Additionally, the global account subdomain is just your global account identifier with a -ga
suffix. Here’s a screenshot of the temporary trial account I set up for this set of examples, where the relationship between the global account identifier and the global account subdomain can be seen:
Now you’ve logged in, run btp
again to see the difference. You should now see the version of the server to which you’re connected and authenticated, confirmation of your user identification, and also the “current target”, being the global account that you specified (via the subdomain) when you logged in. The output should look something like this:
SAP BTP command line interface (client v2.8.0)
Usage: btp [OPTIONS] ACTION [GROUP/OBJECT] [PARAMS]
CLI server URL: https://cpcli.cf.eu10.hana.ondemand.com (server v2.8.0)
User: P0003480944 (sapdeveloper@example.com)
Configuration: /home/user/.cache/.btp/config.json
Current target:
Global account (subdomain: 82715b8dtrial-ga)
Tips:
For information about the targeting mechanism, use 'btp --help target'.
To display general help, use 'btp --help'.
OK
The btp CLI also offers a way to log in through the browser, with the
--sso
option.
Understanding targets
Let’s dwell on the “target” concept for a moment, it’s important. The btp CLI has a command context for calls. At the outset it’s only set at the top level, to the global account that you specified when you logged in. All actions that work at a global account level will by default target this global account.
You’ll discover that many of the actions you want to perform with the btp CLI will be at the subaccount level – at the level of your trial subaccount, effectively. You can specify a target subaccount too. Let’s do this now. Given that our subaccount is “trial” (as we can see from the screenshot earlier), let’s try:
btp target --subaccount trial
We get this:
Subaccount 'trial' does not exist in the current global account. Make sure to provide the ID of a subaccount of the current global account.
Tip:
To find your subaccount ID, use 'btp list accounts/subaccount'.
ERROR
Hmm, ok. Well, let’s follow the advice we’re given:
btp list accounts/subaccount
Pause for a second to consider the
ACTION [GROUP/OBJECT]
command structure we saw earlier – here we’re seeing a nice example of that.
There’s our trial account in the list that’s produced:
subaccounts in global account 906b8d84-2f2c-429d-8ce4-c1bf166aeb08...
subaccount id: display name: subdomain: region: beta-enabled: parent id: parent type: state: state message:
b8a33bf9-b155-4736-aadf-582dae8fd65a trial 82715b8dtrial eu10 true 906b8d84-2f2c-429d-8ce4-c1bf166aeb08 global account OK Updated tenant status to ACTIVE
OK
It’s the ID that’s required:
btp target --subaccount b8a33bf9-b155-4736-aadf-582dae8fd65a
The ID is what you see when selecting “More Info” from the three-dots menu on the “trial” subaccount card in the screenshot we saw earlier.
The result of specifying the ID in the target command is what we’re looking for:
Targeting subaccount 'b8a33bf9-b155-4736-aadf-582dae8fd65a'.
Commands that only work on global account level will be executed in the parent global account.
Current target:
Global account (subdomain: 82715b8dtrial-ga)
└─ Subaccount (ID: b8a33bf9-b155-4736-aadf-582dae8fd65a)
Tips:
To execute a command in the parent global account, use parameter '-ga' without value.
To execute a command in a different context, specify the subaccount, directory, or global account in the command.
OK
This is already more useful for us with our trial accounts on the Business Technology Platform. It’s a good setup with which to continue our journey of discovery.
Let’s end this post with a final command, to examine details of our subaccount we’re now targetting:
btp get accounts/subaccount
If we hadn’t already specified the subaccount as part of the target, we’d have received an error at this point:
Constraint violated - you must provide parameter 'ID'.
Usage: btp [OPTIONS] get accounts/subaccount ID --global-account SUBDOMAIN
ERROR
However, because we’ve stored the identification of our trial subaccount using the target
command, we get what we’re looking for:
Showing subaccount details for b8a33bf9-b155-4736-aadf-582dae8fd65a...
subaccount id: b8a33bf9-b155-4736-aadf-582dae8fd65a
display name: trial
description:
subdomain: 82715b8dtrial
region: eu10
created by:
beta-enabled: true
used for production: false
parent id: 906b8d84-2f2c-429d-8ce4-c1bf166aeb08
parent type: global account
state: OK
state message: Updated tenant status to ACTIVE
OK
Great! In the next post, we take a quick look at managing configuration: SAP Tech Bytes: btp CLI – managing configuration.
SAP Tech Bytes is an initiative to bring you bite-sized information on all manner of topics, in video and written format. Enjoy!
Hi DJ,
I might be completely overlooking something here, but there seems to be an important feature missing from btp CLI: built-in global account listing and selection
If you logon to BTP your global accounts are listed. I can only presume this must be possible to include this listing in the btp CLI!
Hey Pieter - do you mean listing more than one global account from a single authenticated btp CLI "instance"? Can you please help me out with a bit more detail? I would love to take this back to the team. Thanks, and have a great weekend!
Yes, exactly that. My user account gives me access to certain global accounts on a certain datacenter. If you have multiple global accounts (many of us do as we are working for multiple customers), then it would be nice to be able to list and target the global account using the btp CLI.
This means logging in to the btp CLI should work by just providing the data center URL, the username and password or --sso option.
Thanks for clarifying, Pieter. I've passed on this good question to the team. I'll update you here when I hear more. Cheers! DJ