pearc19-hpc-in-the-cloud GitHub

Tutorial: Getting Started with Tapis CLI

The following instructions will guide you through setting up Tapis CLI. As an aside, everything we do today can also be accomplished from a command line interface or by directly calling API endpoints.

The Tapis CLI commands all respond with help for -h and return back information on the parameters that can be passed.

Need help? Ask your questions using the TACC Cloud Slack Channel

Initial Requirements

Before getting started, you need to have the following:

Any questions? Join the TACC CLOUD SLACK CHANNEL and ask away.

Command Line Access

We won’t install it in this workshop (since it is already installed on the VM), but everything we do today can also be done from the standard shell using the Tapis CLI tools.

Open a terminal in your Jupyter instance and that is what we will use to run the CLI commands.

Jump to the Authentication section for the workshop.

Installing the Tapis CLI Tools (Skip for Workshop- this is at home )

Tapis has a downloadable set of command line tools that make it easier to work with the API from the shell. Using these scripts is generally easier than hand-crafting cURL commands, but if you prefer that route, consult the Tapis API Documentation. We include these scripts in the training virtual machines and supplement them with additional support scripts, example files, and documents.

During the course, we will use the Jetstream Cloud virtual machines, but if you have a shell on your personal computer, you can install these tools on your own later.

To use access the CLI for this tutorial you can open a Terminal in Jupyter which give you access to the shell in the Jetstream VM, OR ssh into the system from you own terminal:

ssh ubunut@jetstreamVM_ip_address

Install the CLI tools (Skip for Workshop- this is at home )

The CLI tools and instructions for installation can be found in the CLI repository


Tapis has robust Authentication/Authorization pathways - we could easliy spend an hour or more discussing them, but will keep our focus simple for this tutorial.

The Tapis API uses OAuth 2 for managing authentication and authorization. OAuth 2 is an open standard for access delegation, commonly used as a way for Internet users to grant websites or applications access to their information on other websites but without giving them the passwords.

Just understand that instead of passing a username and password every time we want to make an authenticated/authorized request to the Tapis APIs we will be usig an Access Token that has a defined expiration - this keeps our credentials safe and ensures that if someone where to obtain the token it could not be used forever.

Run the following in the CLI

Please run /agave-cli/bin/tenants-init to initialize your client before attempting to interact with the APIs.

We will see that we have to initialize some things before we can use Tapis.

Initialize the CLI

The first time you install the CLI tools on a computer, you need to initialize it. You can initialize the TACC tenant by runnning:

> auth-session-init
ID                   NAME                                     URL        VDJ Server                     
sgci                 Science Gateways Community Institute          CyVerse Science APIs           
sd2e                 SD2E Tenant                    
3dem                 3dem Tenant                    
designsafe           DesignSafe                               Araport                                    TACC                           
irec                 iReceptor                                 Agave Public Tenant            
bridge               Bridge                         
portals              Portals Tenant                 

Please specify the ID for the tenant you wish to interact with:
Creating a client...
API username: train100
API password:
Created client 5c8c91edb474 - Autogenerated client
Getting oauth bearer tokens...

Select the ‘’ tenant and then use the username and password provided for this tutorial.

The ‘auth-session-init’ command creates a Tapis client and then request an API token and will then place the TACC tenant,client and API token information into a cache in ~/.agave/current. This is the file that the CLI tools will look for when making API calls so that you don’t have to enter those parameters for every call.

Creating a Client

The Tapis API uses OAuth 2 for managing authentication and authorization. Before you work with Tapis, you must create an OAuth client application and record the API keys that are returned. This is a one-time action per machine that you use the CLI on and the ‘auth-session-init’ can take care of this. In the event you need to create your own client you can pass additional parameters to the ‘auth-session-init’ command. For instance if we want to make a new client.

> auth-session-init -h
usage: auth-session-init [-h] [-c CACHEDIR] [--tenants TENANTS] [-t TENANT]
                         [-u USERNAME] [-N CLIENT_NAME] [-D DESCRIPTION]

Create a new Agave oauth client

optional arguments:
  -h, --help            show this help message and exit
  -c CACHEDIR, --cachedir CACHEDIR
                        Directory to save confiurations in.
  --tenants TENANTS     URL with tenants listings.
  -t TENANT, --tenant TENANT
                        Tenant id for session.
  -u USERNAME, --username USERNAME
                        Session username.
                        Name of client.
                        Description of client.

> auth-session-init -N myclient1
Client 'myclient1' is not saved in /root/.agave, so we will create it...
Creating a client...
API password:
Created client myclient1 - Autogenerated client
Getting oauth bearer tokens...
API password:

Note: The -N flag allows you to specify a machine-readable name for your client and -D provides the description.

You will need access to the consumerKey and consumerSecret values when setting up on other hosts. So, please take a moment and record client_name, consumerKey, and consumerSecret somewhere safe. If you lose these values, you can create a new instance of the client by deleting the old client (clients-delete CLIENT_NAME) and creating it again (or create a new client with a different name).

OAuth 2 API authentication token

Tokens are a form of short-lived, temporary authenticiation and authorization used in place of your username and password. To interact with Tapis, you will need to acquire one. Each Tapis token, typically, expires after 4 hours, but can easily be refreshed.

On a host where you have configured a Tapis OAuth2 client already, the CLI command to get a new token is:

> auth-tokens-create -v
API password:

You will then be prompted to enter your API password. Type your user password. At this point, you should receive an affirmation of success in your terminal that resembles this one:

Token for successfully refreshed and cached for 13605 seconds
  "scope": "default",
  "token_type": "bearer",
  "expires_in": 13605,
  "refresh_token": "fd38287337b5312933eea555555",
  "access_token": "f940624e12e7186117443ee555555"

NOTE that the CLI will cache the new access and refresh tokens in the ~/.agave/current file.

Refreshing your token

This tutorial won’t take very long, but if you are interrupted and come back later, you might find your token has expired. You can always refresh a token as follows:

> auth-tokens-refresh -v

A successful refresh should appear:

Token for successfully refreshed and cached for 14400 seconds
  "scope": "default",
  "token_type": "bearer",
  "expires_in": 14400,
  "refresh_token": "b4b5c3e5b7c77862af8088c4a92c6a25",
  "access_token": "561335afda3b35654c84dc6d483f7ccf"

This topic is covered in great detail at the Tapis Authorization Guide

NOTE that most CLI commands will attempt to do a token refresh on your behalf if the access token is expired.

Command Help

Note that all the CLI commands take the ‘-h’ flag to display a short description and the accept parameters for the command.