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.