Quick Start

This chapter walks you through the general process of setting up and using Tower CLI. It starts with CLI usage and ends with API usage. For futher details, please see API Reference and Workflow Management.

It is assumed you have a Tower backend available to talk to and Tower CLI installed. Please see the Installation chapter for instructions on installing Tower CLI.

First of all, make sure you know the name of the Tower backend, like tower.example.com, as well as the username/password set of a user in that Tower backend, like user/pass. These are connection details necessary for Tower CLI to communicate to Tower. With these prerequisites, run

$ tower-cli config host tower.example.com
$ tower-cli login username
Password:

The first Tower CLI command, tower-cli config, writes the connection information to a configuration file (~/.tower-cli.cfg, by default), and subsequent commands and API calls will read this file, extract connection information and interact with Tower. See details of Tower CLI configuration in API Reference and tower-cli config --help.

The second command, tower-cli login, will prompt you for your password and will acquire an OAuth2 token (which will also be saved to a configuration file) with write scope. You can also request read scope for read-only access:

$ tower-cli login username --scope read
Password:

Note

Older versions of Tower (prior to 3.3) do not support OAuth2 token authentication, and instead utilize per-request basic HTTP authentication:

$ tower-cli config host tower.example.com
$ tower-cli config username user
$ tower-cli config password pass

Next, use Tower CLI to actually control your Tower backend. The CRUD operations against almost every Tower resource can be done using Tower CLI. Suppose we want to see the available job templates to choose for running:

$ tower-cli job_template list

A command-line-formatted table would show up, giving general summary of (maybe part of) the available job templates. Note the actual HTTP(S) response is in JSON format, you can choose to see the JSON response itself instead using --format flag.

$ tower-cli job_template list --format json

Other than normal resource CRUD operations, Tower CLI can be used to launch and monitor executable resources like job templates and projects. Suppose we have had the ID of the job template we want to execute from the previous list call, we can launch the job template by:

$ tower-cli job launch -J <ID of the job template> --monitor

This command will POST to Tower backend to launch the job template to be executed, and monitor the triggered job run by dumping job stdout in real-time, just as what Tower UI does.

The best CLI help you can get is from --help option. Each Tower CLI command is guaranteed to have a --help option instructing the command hierarchy and detailed usage like command format the meaning of each available command option. Use --help whenever you have questions about a Tower CLI command.

Under the hood, Tower CLI is composed of an API engine and a wrapper layer around it to make it a CLI. Using API of Tower CLI gives you finer-grained control and makes it easy to integrate Tower CLI into your python scripts.

The usage of Tower CLI’s API is two-phased: get resource and call its API. First you get the type of resource you want to interact with.

import tower_cli

res = tower_cli.get_resource('job_template')

Due to legacy reasons, we use a non-traditional way of importing resource class, tower_cli.get_resource. Alternatively, you can use the old way by using import alias:

from tower_cli.resources.job_template import Resource as JobTemplate

res = JobTemplate()

Then, interaction with Tower would be as easy as straight-forward resource public method calls, like

jt_list = res.list()
tower_cli.get_resource('job').launch(job_template=1, monitor=True)

More API usage can be found in API reference.