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.

Environment Setup