Provided by: ansible-tower-cli_3.2.0-2_all 
NAME
tower_cli - tower_cli Documentation
tower-cli is a command line tool for Ansible Tower. It allows Tower commands to be easily run from the
Unix command line. It can also be used as a client library for other python apps, or as a reference for
others developing API interactions with Tower’s REST API.
ABOUT TOWER
Ansible Tower is a GUI and REST interface for Ansible that supercharges it by adding RBAC, centralized
logging, autoscaling/provisioning callbacks, graphical inventory editing, and more.
Tower is free to use for up to 30 days or 10 nodes. Beyond this, a license is required.
CAPABILITIES
This command line tool sends commands to the Tower API. It is capable of retrieving, creating, modifying,
and deleting most resources within Tower.
A few potential uses include:
• Launching playbook runs (for instance, from Jenkins, TeamCity, Bamboo, etc)
• Checking on job statuses
• Rapidly creating objects like organizations, users, teams, and more
TABLE OF CONTENTS
Installation
Install from Package Managers
Tower CLI is available as a package on PyPI.
The preferred way to install is through pip:
$ pip install ansible-tower-cli
Build from Source
ansible-tower-cli may also be consumed and built directly from source.
$ git clone https://github.com/ansible/tower-cli.git
Then, inside tower_cli directory, run
$ make install
and follow the instructions.
If you are not familar with ansible-tower-cli’s dependency tree, we suggested building source in a fresh
virtual environment to prevent any dependency conflict.
Install the Right Version
REST API of Ansible Tower is versioned, and each API version is supported by a subset, rather than all,
of ansible-tower-cli versions. Make sure you are pairing your Tower backend with a right version of
ansible-tower-cli, specifically:
• If you are using Tower 3.2.0 and beyond, API v2 is available, you should use ansible-tower-cli 3.2.0
and beyond.
• If you are using a Tower version lower than 3.2.0, only API v1 is available, you should use
ansible-tower-cli versions lower than 3.2.0.
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 details, please see API and CLI references in subsequent chapters.
It is assumed you have a Tower backend available to talk to and Tower CLI installed. Please see
‘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 information
necessary for Tower CLI to communicate to Tower. With these prerequisites, run
$ tower-cli config host tower.example.com
$ tower-cli config username user
$ tower-cli config password pass
The first Tower CLI command, tower-cli config. writes the connection informations to a configuration file
(~/.tower-cli.cfg in this case), and subsequent commands and API calls will read this file, extract
connection information and talk to Tower as the specified user. See details of Tower CLI configuration in
API reference and tower-cli config --help.
Then, 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:
import 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.
API Reference
NOTE: This API documentation assumes you are using 3.2.0 and higher versions of ansible-tower-cli. If you
are using a lower version than 3.2.0, there is no guarantee API usages in this documentation would work
as expected.
Introduction
Like Tower UI, Tower CLI is a client talking to multiple REST services of Tower backend, but via Python
script or UNIX command line. Thus the usage of Tower CLI’s APIs are pretty straight-forward: get a
resource corresponding to its counterpart in Tower backend, and call public methods of that resource,
which in term requests specific REST endpoint and fetch/render response JSON. Here is a simple example of
creating a new organization using Tower CLI in Python:
from tower_cli import get_resource
from tower_cli.exceptions import Found
from tower_cli.conf import settings
with settings.runtime_values(username='user', password='pass'):
try:
res = get_resource('organization')
new_org = res.create(name='foo', description='bar', fail_on_found=True)
except Found:
print('This organization already exists.')
assert isinstance(new_org, dict)
print(new_org['id'])
The above example shows the pattern for most Tower CLI API use cases, which is composed of 3 parts:
runtime configuration, fetch resource and invoke its public methods, and exception handling.
Tower CLI needs a set of configurations to function properly, all configuration settings are stored in
singleton object tower_cli.conf.settings, which provides a public context manager runtime_values to
temporary override settings on file with temporary runtime values. see more about Tower CLI
configurations in ‘Configuration’ section.
Most of the resources listed at Tower’s endpoint /api/v2/ have client-side proxy classes in Tower CLI.
The two main ways of getting resource proxies in Tower CLI are:
from tower_cli import get_resource
res = get_resource('<resource name>')
and
import tower_cli.resources.<resource module name>.Resource as <alias>
res = <alias>()
A typical resource in Tower CLI has 2 components: fields and public methods. Resource fields can be seen
as wrappers around actual resource fields exposed by Tower REST API. They are generally used by public
methods to create and modify resources and filter when searching for specific resources; Public methods
are the actual wrappers around querying Tower REST APIs, they can be used both for general CRUD
operations against Tower resources, like delete a user, and for specific tasks like launching an ad hoc
command, monitoring a job run or constructing a workflow graph from script.
In the table of contents below, all available Tower CLI resources are listed, the documentation for each
of them all follow the same structure: a ‘Description’ section which gives an introduction to the
resource; a ‘Fields Table’ section which lists all available fields of that resource; and a ‘API
Specification’ section, which expands the usage detail of every available public method.
Note most public methods have a keyword argument **kwargs. This argument basically contains and only
contains resource fields, unless specified.
Any usage errors or connection exceptions are thrown as subclasses of tower_cli.exceptions.TowerCLIError,
see ‘Exceptions’ section below for details.
Table of Contents
Configuration
In Tower CLI, there are a number of configuration settings available to users. These settings are mostly
used to set up connection details to Tower backend, like hostname of Tower backend and user name/password
used for authentication; some are also used for other purposes, like toggle on/off colored stdout. Here
is a list of all available Tower CLI settings:
────────────────────────────────────────────────────────────────────────────────
Key Value Type / Value Default Description
────────────────────────────────────────────────────────────────────────────────
color Boolean/’true’ Whether to use colored
output for highlighting or
not.
────────────────────────────────────────────────────────────────────────────────
format String with options Output format. The “human”
(‘human’, ‘json’, format is intended for
‘yaml’)/’human’ humans reading output on the
CLI; the “json” and “yaml”
formats provide more data.
[CLI use only]
────────────────────────────────────────────────────────────────────────────────
host String/‘127.0.0.1’ The location of the Ansible
Tower host. HTTPS is assumed
as the protocol unless “‐
http://” is explicitly
provided.
────────────────────────────────────────────────────────────────────────────────
password String/’‘ Password to use to
authenticate to Ansible
Tower.
────────────────────────────────────────────────────────────────────────────────
username String/’‘ Username to use to
authenticate to Ansible
Tower.
────────────────────────────────────────────────────────────────────────────────
verify_ssl Boolean/’true’ Whether to force verified
SSL connections.
────────────────────────────────────────────────────────────────────────────────
verbose Boolean/’false’ Whether to show information
about requests being made.
────────────────────────────────────────────────────────────────────────────────
description_on Boolean/’false’ Whether to show description
in human-formatted output.
[CLI use only]
────────────────────────────────────────────────────────────────────────────────
certificate String/’‘ Path to a custom certificate
file that will be used
throughout the command.
Ignored if –insecure flag if
set in command or verify_ssl
is set to false
────────────────────────────────────────────────────────────────────────────────
use_token Boolean/’false’ Whether to use token-based
authentication.
┌────────────────┬──────────────────────────────┬──────────────────────────────┐
│ │ │ │
--
AUTHOR
Alan Rominger, Luke Sneeringer, Aaron Tan
COPYRIGHT
2017, Ansible by Red Hat
Oct 31, 2017 TOWER_CLI(1)