tower-cli(1) — ansible-tower-cli — Debian buster

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 familiar with ansible-tower-cli’s dependency tree, we suggested building source in a fresh virtual environment to prevent any dependency conflict.

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_ref and cli_ref.

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_ref 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 username 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.

CLI Reference¶

CLI invocation generally follows this format:

$ tower-cli {resource} {action} ...

The “resource” is a type of object within Tower (a noun), such as user, organization, job_template, etc.; resource names are always singular in Tower CLI (so it is tower-cli user, never tower-cli users).

The “action” is the thing you want to do (a verb). Most Tower CLI resources have the following actions–get, list, create, modify, and delete–and have options corresponding to fields on the object in Tower.

Some examples:

# List all users.
$ tower-cli user list
# List all non-superusers
$ tower-cli user list --is-superuser=false
# Get the user with the ID of 42.
$ tower-cli user get 42
# Get the user with the given username.
$ tower-cli user get --username=guido
# Create a new user.
$ tower-cli user create --username=guido --first-name=Guido \
                        --last-name="Van Rossum" --email=guido@python.org \
                        --password=password1234
# Modify an existing user.
# This would modify the first name of the user with the ID of "42" to "Guido".
$ tower-cli user modify 42 --first-name=Guido
# Modify an existing user, lookup by username.
# This would use "username" as the lookup, and modify the first name.
# Which fields are used as lookups vary by resource, but are generally
# the resource's name.
$ tower-cli user modify --username=guido --first-name=Guido
# Delete a user.
$ tower-cli user delete 42
# List all jobs
$ tower-cli job list
# List specific page of job list
$ tower-cli job list --page=1
# Launch a job.
$ tower-cli job launch --job-template=144
# Monitor a job.
$ tower-cli job monitor 95
# Filter job list for currently running jobs
$ tower-cli job list --status=running
# Export all objects
$ tower-cli receive --all
# Export all credentials
$ tower-cli receive --credential all
# Export a credential named "My Credential"
$ tower-cli receive --credential "My Credential"
# Import from a JSON file named assets.json
$ tower-cli send assets.json
# Import anything except an organization defined in a JSON file named assets.json
$ tower-cli send --prevent organization assets.json
# Copy all assets from one instance to another
$ tower-cli receive --tower-host tower1.example.com --all | tower-cli send --tower-host tower2.example.com

When in doubt, help is available!

$ tower-cli --help # help
$ tower-cli user --help # resource specific help
$ tower-cli user create --help # command specific help

In specific, tower-cli --help lists all available resources in the current version of Tower CLI:

$ tower-cli --help
Usage: tower-cli [OPTIONS] COMMAND [ARGS]...
Options:
  --version  Display tower-cli version.
  --help     Show this message and exit.
Commands:
  ad_hoc                 Launch commands based on playbook given at...
  config                 Read or write tower-cli configuration.
  credential             Manage credentials within Ansible Tower.
  credential_type        Manage credential types within Ansible Tower.
  empty                  Empties assets from Tower.
  group                  Manage groups belonging to an inventory.
  host                   Manage hosts belonging to a group within an...
  instance               Check instances within Ansible Tower.
  instance_group         Check instance groups within Ansible Tower.
  inventory              Manage inventory within Ansible Tower.
  inventory_script       Manage inventory scripts within Ansible...
  inventory_source       Manage inventory sources within Ansible...
  job                    Launch or monitor jobs.
  job_template           Manage job templates.
  label                  Manage labels within Ansible Tower.
  node                   Manage nodes inside of a workflow job...
  notification_template  Manage notification templates within Ansible...
  organization           Manage organizations within Ansible Tower.
  project                Manage projects within Ansible Tower.
  receive                Export assets from Tower.
  role                   Add and remove users/teams from roles.
  schedule               Manage schedules within Ansible Tower.
  send                   Import assets into Tower.
  setting                Manage settings within Ansible Tower.
  team                   Manage teams within Ansible Tower.
  user                   Manage users within Ansible Tower.
  version                Display version information.
  workflow               Manage workflow job templates.
  workflow_job           Launch or monitor workflow jobs.

and tower-cli {resource} --help lists all available actions:

$ tower-cli user --help
Usage: tower-cli user [OPTIONS] COMMAND [ARGS]...
  Manage users within Ansible Tower.
Options:
  --help  Show this message and exit.
Commands:
  copy    Copy a user.
  create  Create a user.
  delete  Remove the given user.
  get     Return one and exactly one user.
  list    Return a list of users.
  modify  Modify an already existing user.

and tower-cli {resource} {action} --help shows details of the usage of this action:

$ tower-cli user create --help
Usage: tower-cli user create [OPTIONS]
  Create a user.
  Fields in the resource's --identity tuple are used for a lookup; if a
  match is found, then no-op (unless --force-on-exists is set) but do not
  fail (unless --fail-on-found is set).
Field Options:
  --username TEXT              [REQUIRED] The username field.
  --password TEXT              The password field.
  --email TEXT                 [REQUIRED] The email field.
  --first-name TEXT            The first_name field.
  --last-name TEXT             The last_name field.
  --is-superuser BOOLEAN       The is_superuser field.
  --is-system-auditor BOOLEAN  The is_system_auditor field.
Local Options:
  --fail-on-found    If used, return an error if a matching record already
                     exists.  [default: False]
  --force-on-exists  If used, if a match is found on unique fields, other
                     fields will be updated to the provided values. If False,
                     a match causes the request to be a no-op.  [default:
                     False]
Global Options:
  --certificate TEXT              Path to a custom certificate file that will
                                  be used throughout the command. Overwritten
                                  by --insecure flag if set.
  --insecure                      Turn off insecure connection warnings. Set
                                  config verify_ssl to make this permanent.
  --description-on                Show description in human-formatted output.
  -v, --verbose                   Show information about requests being made.
  -f, --format [human|json|yaml|id]
                                  Output format. The "human" format is
                                  intended for humans reading output on the
                                  CLI; the "json" and "yaml" formats provide
                                  more data, and "id" echos the object id
                                  only.
  -p, --tower-password TEXT       Password to use to authenticate to Ansible
                                  Tower. This will take precedence over a
                                  password provided to `tower config`, if any.
  -u, --tower-username TEXT       Username to use to authenticate to Ansible
                                  Tower. This will take precedence over a
                                  username provided to `tower config`, if any.
  -h, --tower-host TEXT           The location of the Ansible Tower host.
                                  HTTPS is assumed as the protocol unless
                                  "http://" is explicitly provided. This will
                                  take precedence over a host provided to
                                  `tower config`, if any.
  --use-token                     Turn on Tower's token-based authentication.
                                  No longer supported in Tower 3.3 and above
Other Options:
  --help  Show this message and exit.

There are generally 3 categories of options for each action to take: field options, local options and global options. Field options can be seen as wrappers around actual resource fields exposed by Tower REST API. They are generally used to create and modify resources and filter when searching for specific resources; local options are action-specific options, they provide fine-grained modification of the behavior of a resource action. for example, --fail-on-found option of a create action will fail the command if a matching record already exists in Tower backend; global options are used to set runtime configuration settings, functioning the same way as context manager tower_cli.conf.Settings.runtime_values in api-ref-conf.

Config Command Options¶

key-value options available for tower-cli config <key> <value> command¶

Key	Value Type/Default	Description
col or	Boolean/’true’	Whether to use colored output for highlighting or not.
for mat	String with options (‘human’, ‘json’, ‘yaml’)/’human’	Output format. The “human” format is intended for humans reading output on the CLI; the “json” and “yaml” formats provide more data.
hos t	String/‘127.0.0.1 ‘	The location of the Ansible Tower host. HTTPS is assumed as the protocol unless “http://” is explicitly provided.
`` pas sword ``	String/’‘	Password to use to authenticate to Ansible Tower.

`` use rname ``

String/’‘

Username to use to authenticate to Ansible Tower.

ver ify_s sl	Boolean/’true’	Whether to force verified SSL connections.
`` ver bose` `	Boolean/’false’	Whether to show information about requests being made.

des cript ion_o n	Boolean/’false’	Whether to show description in human-formatted output.
cer tific ate	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 _toke n	Boolean/’false’	Whether to use token-based authentication.

Environment Variables¶

All of the above options can also be set using environment variables. The default behavior is to allow environment variables to override your tower-cli.cfg settings, but they will not override config values that are passed in on the command line at runtime. Below is a table of the available environment variables.

Variable Mapping¶

Environment Variable	Tower Config Key
TOWER_COLOR	color
TOWER_FORMAT	format
TOWER_HOST	host
TOWER_PASSWORD	password
TOWER_USERNAME	username
TOWER_VERIFY_SSL	verify_ssl
TOWER_VERBOSE	verbose
TOWER_DESCRIPTION_ON	description_on
TOWER_CERTIFICATE	certificate
TOWER_USE_TOKEN	use_token

Notes¶

•: Under the hood we use the SSL functionality of requests, however the current requests version has checkings on a deprecated SSL certificate field commonName (deprecated by RFC 2818). In order to prevent any related usage issues, please make sure to add subjectAltName field to your own certificate in use. We will update help docs as soon as changes are made on the requests side.

Versioning of tower-cli¶

Tower-CLI is a command-line interface and python library to interact with Ansible Tower and AWX. Only versions of tower-cli can successfully interact with only a certain subset of versions of Ansible Tower or AWX, and this document is meant to outline the policy.

API Versions¶

Ansible Tower and AWX communicate with clients through a particular API version, so that each version forms a stable API for Ansible Tower. Each version of tower-cli also has a corresponding API version.

Supported Versions with Ansible Tower¶

The following table summarizes the policy of supported versions.

tower-cli	API version	Tower version
3.1.x	v1	3.2.x and earlier
current	v2	3.2.x and later

This means that the release series 3.1.x is still open for fixes in order to support communication with the v1 API and all Tower versions that support that. Many elements of functionality are removed in the transition to v2, so they are no longer carried with the current tower-cli version.

Policy with AWX Versions¶

Compatibility between tower-cli and the AWX project is only considered for the most recent development version of tower-cli and most recent version of AWX.

API Version Upgrade Guide¶

If you upgrade tower-cli across an API version change, existing scripts will be broken.

This section highlights the most major backward-incompatible changes that need to be taken into account in order to migrate your scripts.

API v1->v2¶

In API v2, credentials have a new related model “credential_type”. This enables custom credential types, and that old types now need to reference the build-in credential types instead of the old flat-text kind field.

Additionally, to allow fully arbitrary credential types, the fields used by the credential in creating the necessary runtime environment are now nested inside of a dictionary called inputs.

old:

$ tower-cli credential create --name="AWS creds" --team=Ops --kind=aws --username=your_username --password=password

new:

$ tower-cli credential create --name="AWS creds" --team=Ops --credential-type="Amazon Web Services" --inputs='{"username": "your_username", "password": "password"}'

When attaching credentials to job templates, the related link structure has changed.

API v1 options:

–machine-credential
–cloud-credential
–network-credential

API v2 options:

–credential
–vault-credential
Related many-to-many extra_credentials

In order to add “extra” credentials (what used to be cloud credential), use the association method, tower-cli job_template associate_credential ….

In API v2, only “manual” groups can be created directly. The parameters that used to be provided to a group to sync to a cloud source now must be directly given to its inventory source.

old:

$ tower-cli group create --name=EC2 --credential="AWS creds" --source=ec2 --description="EC2 hosts" --inventory=Production

new:

$ tower-cli inventory_source create --name=EC2 --credential="AWS creds" --source=ec2 --description="EC2 hosts" --inventory=Production

To run an inventory update, use the tower-cli inventory_source update command.

Version-specific Secondary Install¶

In order to use different versions of tower-cli simultaneously in order to interact with different servers hosting different API versions, you can use this tool packaged in the source code.

For example:

$ make install_v1

This will install a new CLI entry point, tower-cli-v1, which will behave the same as tower-cli. However, this installation will persist even after upgrading the main program. This also provides the python package tower_cli_v1.

Important note: the configuration file is also separate from the secondary install, so you must re-enter your URL and credentials.

If you want to be sure that you re-install tower-cli-v1, you can do:

$ make v1-refresh

The v1 install is only possible with the v1 branch in the source tree. The master branch currently tracks API v2, and the prior instructions will work for a v2 secondary install, replacing v1 with v2.

Notification Template Management¶

Introduction - What Notification Templates Are¶

Starting with Ansible Tower 3.0, users can create and associate notification templates to job templates. Whenever a job template undergoes a successful/unsuccessful job run, all its related notification templates will send out notifications to corresponding notification receiver, indicating the status of job run.

Managing Notification Templates with tower-cli¶

To see the commands available for notification templates, see tower-cli notification_template --help. Within a specific command, get the help text with tower-cli notification_template <command> --help.

Notification templates suppport all typical CRUD operations that control other resources through tower-cli: get, list, create, modify and delete. On the other hand, uses can use new command tower-cli job_template associate_notification and tower-cli job_tempate disassociate_notification to (dis)associate an existing notification to/from a job template.

Basic Operations¶

CRUD operations on notification templates are basically the same as that of typicall existing resources, e.g. inventory. There are, however, some points due to the nature of notification templates that needs to be careful with:

There are two options in create, --job-template and --status, which controls the create mode: providing these options will create a new notification template and associate it with the specified job template. Notification templates will be created isolatedly if these options are not provided. You can find more information in Tower’s official documentation.
When looking at the help text of certain notification template commands, note a large portion of the available options are prefixed by a label like [slack]. These are special configuration-related options which are composing elements of a notification template’s destination configuration. You can find more information about those options in Tower’s official documentations. These options plus --notification-configuration option form configuration-related options.
Configuration-related options are not functioning options in get, list and delete, meaning they will be ignored under these commands even provided.
The label prefixing configuration-related options indicate the type of notification destination this option is used for. When creating a new notification template with certain destination type (controlled by --notification-type option), all non-default related configuration-related options must be provided.
When modifying an existing notification template, not every configuration-related option has to be provided(but encryped fields must, even you are not changing it!). But if this modification modifies destination type, all non-default related configuration-related options must be provided.
--notification-configuration option provides a json file specifying the configuration details. All other configuration-related options will be ignored if `–notification-configuration`` is provided.

Detailed Example¶

# Create a notification template in isolation.
tower-cli notification_template create --name foo --description bar --notification-type slack --channels a --channels b --token hey --organization Default
# Create a notification template under an existing job template.
tower-cli notification_template create --name foo --description bar --notification-type slack --channels a --channels b --token hey --job-template 5 --organization Default
# Get exactly one notification template.
tower-cli notification_template get --name foo
# Get a list of notification templates under certain criteria.
tower-cli notification_template list --notification-type irc
# Modify an existing notification.
tower-cli notification_template modify --description foo --token hi 17
# Delete an existing notification template.
tower-cli notification_template delete --name foo
# Associate a job template with an existing notification template.
tower-cli job_template associate_notification_template --job-template 5 --notification-template 3
# Disassociate a job template with an existing notification template.
tower-cli job_template disassociate_notification_template --job-template 5 --notification-template 3

Role Management¶

Introduction - What Roles Are¶

Starting with Ansible Tower 3.0, roles are the objects used to manage permissions to various resources within Tower. Each role represents:

A type of permission like “use”, “update”, or “admin”
A resource that this permission applies to, like an inventory or credential

This is “Role Based Access Control” or RBAC. Each role may have several users associated with it, where each of the users gains the specified type of permission. Teams may also be associated with a role, in which case all users who are members of the team receive the specified type of permission.

Managing Roles with tower-cli¶

To see the commands available for roles, see tower-cli roles. Within a specific command, get the help text with tower-cli roles list --help.

The arguments for all role commands follow the same pattern, although not all arguments are mandatory for all commands. The structure follows the following pattern:

tower-cli role <action> --type <choice> --user/team <name/pk> --resource <name/pk>

Roles do not have the typical CRUD operations that control other resources through tower-cli. Roles can not be deleted or created on their own, because they are tied to the resource that they reference. The next section covers what the possible actions are.

Basic Operations¶

The primary use case for roles is adding or removing users and teams from roles. In the following example, a user is added to the project “use” role.

tower-cli role grant --type use --user test_user --project test_project

In the above command “test_user” is the username of a user to receive the new permission, “test_project” is the name of the project they are receiving permission for, and “use” is the type of permission they are receiving. Specifically, this allows test_user to use test_project in a job template.

In a similar fashion, to remove the user from that role:

tower-cli role revoke --type use --user test_user --project test_project

To list the roles on that project:

tower-cli role list --project test_project

Detailed Example¶

The following commands will create an inventory and user and demonstrate the different role commands on them.

# Create the inventory and list its roles
tower-cli inventory create --name 'test_inventory' --organization 'Default'
tower-cli role list --inventory 'test_inventory'
tower-cli role get --type 'use' --inventory 'test_inventory'
# Create a user, give access to the inventory and take it away
tower-cli user create --username 'test_user' --password 'pa$$' --email 'user@example.com'
tower-cli role grant --type 'use' --user 'test_user' --inventory 'test_inventory'
tower-cli role list --user 'test_user' --type 'use'
tower-cli role revoke --type 'use' --user 'test_user' --inventory 'test_inventory'
# Create a team, give access to the inventory and take it away
tower-cli team create --name 'test_team' --organization 'Default'
tower-cli role grant --type 'use' --team 'test_team' --inventory 'test_inventory'
tower-cli role list --team 'test_team' --type 'use'
tower-cli role revoke --type 'use' --team 'test_team' --inventory 'test_inventory'

Organization and Team Roles¶

For assigning users to teams and organizations, include the team or organization flag, and it will be acted on as the resource. Note that teams can be either the resource or the role grantee, depending of whether the --team or the --target-team flag is used.

The following example appoints test_user to the member role of a team and of an organization.

tower-cli role grant --user 'test_user' ---target-team 'test_team' --type 'member'
tower-cli role grant --organization 'Default' --user 'test_user' --type 'member'

These commands are redundant with the tower-cli organization and team associate and disassociate commands.

Survey Management¶

This feature is added in v3.1.0, and v3.1.3 or higher, at least, is recommended.

get help: tower-cli job_template survey --help

View a Survey¶

The name of the job template is known (“survey jt” in this example), and the survey definition is desired.

tower-cli job_template survey --name="survey jt"

Example output, this is the survey spec:

{
  "description": "",
  "spec": [
    {
      "required": true,
      "min": null,
      "default": "v3.1.3",
      "max": null,
      "question_description": "enter a version of tower-cli to install",
      "choices": "v3.0.0\nv3.0.1\nv3.0.2\nv3.1.0\nv3.1.1\nv3.1.2\nv3.1.3",
      "new_question": true,
      "variable": "version",
      "question_name": "Tower-cli version",
      "type": "multiplechoice"
    },
    {
      "required": true,
      "min": null,
      "default": "click\ncolorama\nrequests\nsix\nPyYAML",
      "max": null,
      "question_description": "which package requirements would you like to install/check",
      "choices": "click\ncolorama\nrequests\nsix\nPyYAML",
      "new_question": true,
      "variable": "packages",
      "question_name": "Package requirements",
      "type": "multiselect"
    }
  ],
  "name": ""
}

Save a survey¶

Use the job template modify command to do this. In order to create a functional survey you must do two things:

Save the survey spec - use the --survey-spec option
Enable the survey - use the --survey-enabled option

Example of enabling the survey on a job template:

tower-cli job_template modify --name="hello world infinity" --survey-enabled=true

The --survey-spec option can get the spec from a file by prepending the @ character. If this character is not used, it is assumed that you are giving the JSON data in-line.

Copy a survey to another template¶

The following example saves a survey spec to a file, and then uploads that survey spec to another job template.

# Save the survey spec to file in local directory
tower-cli job_template survey --name="survey jt" > s.json
# Upload that survey to another job template
tower-cli job_template modify --name="another jt" --survey-spec=@s.json --survey-enabled=true

The next example using one line to do the same thing on the command line.

tower-cli job_template modify --name="another jt" --survey-spec="$(tower-cli job_template survey --name='survey jt')" --survey-enabled=true

Workflows¶

Workflows can also have surveys and follow the same pattern. Example:

tower-cli workflow survey --name="workflow with survey"

Workflow Management¶

These docs show how to populate an example workflow in Tower and how to automate the creation or copying of workflows.

Normal CRUD¶

Workflows and workflow nodes can be managed as normal tower-cli resources.

Workflow Creation¶

Create an empty workflow:

tower-cli workflow create --name="workflow1" --organization="Default" --description="example description"

Check the existing workflows with the standard list or get commands.

tower-cli workflow list --description-on

Node Creation¶

Create nodes inside the workflow These all become “root” nodes and will spawn jobs on workflow launch without any dependencies on other nodes. These commands create 2 root nodes.

tower-cli node create -W workflow1 --job-template="Hello World"
tower-cli node create -W workflow1 --job-template="Hello World"

List the nodes inside of the workflow

tower-cli node list -W workflow1

Node Association¶

From the list command, you can find the ids of nodes you want to link assocate_success_node will cause the 2nd node to run on success of the first node. The following command causes node 2 to run on the event of successful completion of node 1.

tower-cli node assocate_success_node 1 2

This operation is only possible when node 2 is a root node. See the Tower documentation for the limitations on the types of node connections allowed.

Auto-creation of the success node, only knowing the parent node id:

tower-cli node assocate_success_node 8 --job-template="Hello world"

Corresponding disassociate commands are also available. Disassociating a node from another node will make it a root node.

Node Network Bulk Management¶

To print out a YAML representation of the nodes of a workflow, you can use the following command. JSON format is also allowed.

tower-cli workflow schema workflow1

Here, “workflow1” is the name of the workflow.

Creating/updating a Schema Definition¶

To bulk-create or buld-update a workflow node network, use the workflow schema command. The schema is JSON or YAML content, and can be passed in the CLI argument, or pointed to a file. The schema is passed as a second positional argument, where the first argument references the workflow.

tower-cli workflow schema workflow2 @schema.yml

The schema can be provided without using a file:

tower-cli workflow schema workflow2 '[{"job_template": "Hello world"}]'

The Schema definition defines the hierarchy structure that connects the nodes. Names, as well as other valid parameters for node creation, are acceptable inside of the node’s entry inside the schema definition.

Links must be declared as a list under a key that starts with “success”, “failure”, or “always”. The following is an example of a valid schema definition.

Example schema.yml file:

- job_template: Hello world
  failure:
  - inventory_source: AWS servers (AWS servers - 42)
  success:
  - project: Ansible Examples
    always:
    - job_template: Echo variable
      success:
      - job_template: Scan localhost

This style may be useful to apply in a script to create a workflow network with a tower-cli command after the constituent resources like the job templates and projects were created by preceding tower-cli commands.

Differences with Machine Formatted Schemas¶

After writing a workflow schema, you may notice differences in how tower-cli subsequently echos the schema definition back to you. The following is what tower-cli might return after writing the above example.

- failure_nodes:
  - inventory_source: 42
  job_template: 45
  success_nodes:
  - always_nodes:
    - job_template: 55
      success_nodes:
      - job_template: 44
    project: 40

Note that the root node data starts with “failure_nodes”, instead of the name of the job template. This will not impact functionality, and manually changing the order will not impact functionality either.

Although this format is harder to read, it does the same thing as the previous schema. The ability to both echo and create schemas can be used to copy the contents of one workflow to another.

As an example, consider 2 workflows. The first has a name “workflow1”, and has its node network populated. The second is named “workflow2” and is empty. The following commands will copy the structure from the first to the second.

tower-cli workflow schema workflow1 > schema.yml
tower-cli workflow schema workflow2 @schema.yml

Idempotence¶

The workflow schema feature populates the workflow node network based on the hierarchy structure. Before creating each node, it attempts to find an existing node with the specified properties in that location in the tree, and will not create a new node if it exists. Also, if an existing node has no correspondence in the schema, the entire sub-tree based on that node will be deleted.

Thus, after running the schema command, the resulting workflow topology will always be exactly the same as what is specified in the given schema file. To continue with the previous example, subsequent invocations of:

tower-cli workflow schema workflow2 @schema.yml
tower-cli workflow schema workflow2 @schema.yml

should not change the network of workflow2, since schema.yml file itself remains unchanged. However

tower-cli workflow schema workflow2 @new_schema.yml

will modify topology of workflow2 to exactly the same as what is specified in new_schema.yml.

Launching Workflow Jobs¶

Use the workflow_job resource to launch workflow jobs. This supports the use of extra_vars, which can contain answers to survey questions. The --monitor and --wait flag are available to poll the server until workflow job reaches a completed status. The --monitor option will print rolling updates of the jobs that ran as part of the workflow. Here is an example of using those features:

tower-cli workflow_job launch -W "echo Hello World" -e a=1 --monitor

Example Commands¶

Examples here are intended to give concrete examples of how the CLI can be used in an automated way. It can also help with testing or the defining of feature requests.

Expect the setup script to take up to 2 minutes to run. Most of this time is waiting for the project source control to sync the examples from github to the tower server.

Setup¶

You should have a version of tower running and configured in the CLI in order to run any scripts or commands here. With your specific data, that can done by the following commands:

$ tower-cli config host tower.example.com
$ tower-cli config username leeroyjenkins
$ tower-cli config password myPassw0rd

Jobs demonstrated in the script do not connect to another machine, and do not require valid machine credentials, so tower-cli config information should be all the unique information necessary.

Create Fake Data¶

You may want to reference the fake data creator for examples on how to create different types of resources.

If you want to run the script, which auto-populates your Tower server with a small set of fake data, run the following:

# Populate the server with fake data and run test jobs
$ cd docs/source/cli_ref/examples/
$ source fake_data_creator.sh

Cleaning Up¶

The teardown script removes all of the objects that the CLI can easily remove. This is not a perfect cleanup, but it performs well enough to get the system ready to run the fake data creator script again.

# Delete the data that was created (with some exceptions)
$ source fake_data_teardown.sh

Warnings¶

It is strongly suggested that you only run these scripts on testing versions of an Ansible Tower host in order to avoid unintended naming conflicts.

Python Module Use Example¶

This bash script example borrows fake data elements from the tower populator script. The tower_populator script provides an example of how to use the tower-cli python modules.

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.

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 (‘human’, ‘json’, ‘yaml’)/’human’	Output format. The “human” format is intended for 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. No longer supported in Tower 3.3 and above

Note: Some settings are marked as ‘CLI use only’, this means although users are free to set values to those settings, those settings only affect CLI but not API usage.

class tower_cli.conf.Settings: A class that understands configurations provided to tower-cli through configuration files or runtime parameters. A signleton object tower_cli.conf.settings will be instantiated and used.
The 5 levels of precedence for settings, listing from least to greatest, are:

defaults: Default values provided
global: Contents parsed from .ini-formatted file /etc/tower/tower_cli.cfg if exists.
user: Contents parsed from .ini-formatted file ~/.tower_cli.cfg if exists.
local: Contents parsed from .ini-formatted file .tower_cli.cfg if exists in the present working directory or any parent directories.
environment: Values from magic environment variables.
runtime: keyworded arguments provided by settings.runtime_values context manager.

Note that .ini configuration file should follow the specified format in order to be correctly parsed:

[general]
<configuration name 1> = <value 1>
<configuration name 2> = <value 2>
...

runtime_values(**kwargs): Context manager that temporarily override runtime level configurations.

Parameters: kwargs (arbitrary keyword arguments) – Keyword arguments specifying runtime configuration settings.
Returns: N/A
Example

>>> import tower_cli
>>> from tower_cli.conf import settings
>>> with settings.runtime_values(username='user', password='pass'):
>>>     print(tower_cli.get_resource('credential').list())

Exceptions¶

APIs of tower_cli raise exceptions defined in tower_cli.exceptions module. Check raise list of resource public method documentation for possible exceptions.

exception tower_cli.exceptions.AuthError(message): An exception class for reporting when a request failed due to an authorization failure.

exception tower_cli.exceptions.BadRequest(message): An exception class for reporting unexpected error codes from Ansible Tower such that 400 <= code < 500.
In theory, we should never, ever get these.

exception tower_cli.exceptions.CannotStartJob(message): An exception class for jobs that cannot be started within Tower for whatever reason.

exception tower_cli.exceptions.ConnectionError(message): An exception class to bubble requests errors more nicely, and communicate connection issues to the user.

exception tower_cli.exceptions.Forbidden(message): An exception class for reporting when a user doesn’t have permission to do something.

exception tower_cli.exceptions.Found(message): An exception class for when a record already exists, and we were explicitly told that it shouldn’t.

exception tower_cli.exceptions.JobFailure(message): An exception class for job failures that require error codes within the Tower CLI.

exception tower_cli.exceptions.MethodNotAllowed(message): An exception class for sending a request to a URL where the URL doesn’t accept that method at all.

exception tower_cli.exceptions.MultipleRelatedError(message): An exception class for errors where we try to find a single related object, and get more than one.

exception tower_cli.exceptions.MultipleResults(message): An exception class for reporting when a request that expected one and exactly one result got more than that.

exception tower_cli.exceptions.NotFound(message): An exception class for reporting when a request went through without incident, but the requested content could not be found.

exception tower_cli.exceptions.RelatedError(message): An exception class for errors where we can’t find related objects that we expect to find.

exception tower_cli.exceptions.ServerError(message): An exception class for reporting server-side errors which are expected to be ephemeral.

exception tower_cli.exceptions.Timeout(message): An exception class for timeouts encountered within Tower CLI, usually for monitoring.

exception tower_cli.exceptions.TowerCLIError(message): Base exception class for problems raised within Tower CLI. This class adds coloring to exceptions.

exception tower_cli.exceptions.UsageError(message): An exception class for reporting usage errors.
This uses an exit code of 2 in order to match click (which matters more than following the erstwhile “standard” of using 64).

exception tower_cli.exceptions.ValidationError(message): An exception class for invalid values being sent as option switches to Tower CLI.

API Reference Table of Contents¶

Ad Hoc Commands¶

Description¶

This resource is used for managing and executing ad hoc commands via Tower. While the rest CRUD operations follow the common usage pattern, an ad hoc command resource cannot be created via the normal way of calling create, but only be created on-the-fly via launch.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
job_explanation	String	The job_explanation field.	False	False	True	False
created	String	The created field.	False	False	True	False
status	String	The status field.	False	False	True	False
elapsed	String	The elapsed field.	False	False	True	False
job_type	Choices: run,check	The job_type field.	False	False	True	True
inventory	Resource inventory	The inventory field.	False	False	True	True
limit	String	The limit field.	False	False	True	False
credential	Resource credential	The credential field.	False	False	True	True
module_name	String	The module_name field.	False	False	True	False
module_args	String	The module_args field.	False	False	True	False
forks	int	The forks field.	False	False	True	False
verbosity	mapped_choice	The verbosity field.	False	False	True	False
become_enabled	bool	The become_enabled field.	False	False	True	False
diff_mode	bool	The diff_mode field.	False	False	True	False

API Specification¶

class tower_cli.resources.ad_hoc.Resource(*args, **kwargs): A resource for ad hoc commands.

cancel(pk=None, fail_if_not_running=False, **kwargs): Cancel a currently running job.

Parameters

pk (int) – Primary key of the job resource to restart.
fail_if_not_running (bool) – Flag that if set, raise exception if the job resource cannot be canceled.
**kwargs – Keyword arguments used to look up job resource object to restart if pk is not provided.

Returns: A dictionary of two keys: “status”, which is “canceled”, and “changed”, which indicates if the job resource has been successfully canceled.
Return type: dict
Raises: tower_cli.exceptions.TowerCLIError – When the job resource cannot be canceled and fail_if_not_running flag is on.

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

launch(monitor=False, wait=False, timeout=None, **kwargs): Launch a new ad-hoc command.

Parameters

monitor (bool) – Flag that if set, immediately calls monitor on the newly launched command rather than exiting with a success.
wait (bool) – Flag that if set, monitor the status of the job, but do not print while job is in progress.
timeout (int) – If provided with monitor flag set, this attempt will time out after the given number of seconds.
**kwargs – Fields needed to create and launch an ad hoc command.

Returns: Result of subsequent monitor call if monitor flag is on; Result of subsequent wait call if wait flag is on; dictionary of “id” and “changed” if none of the two flags are on.
Return type: dict
Raises: tower_cli.exceptions.TowerCLIError – When ad hoc commands are not available in Tower backend.

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

monitor(pk, parent_pk=None, timeout=None, interval=0.5, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='ANSI_X3.4-1968'>, **kwargs): Stream the standard output from a job run to stdout.

Parameters

pk (int) – Primary key of the job resource object to be monitored.
parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be monitored if pk is not set.
timeout (float) – Number in seconds after which this method will time out.
interval (float) – Polling interval to refresh content from Tower.
outfile (file) – Alternative file than stdout to write job stdout to.
**kwargs – Keyword arguments used to look up job resource object to monitor if pk is not provided.

Returns: A dictionary combining the JSON output of the finished job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is finished as expected; “id”, an integer which is the primary key of the job resource object being monitored.
Return type: dict
Raises

tower_cli.exceptions.Timeout – When monitor time reaches time out.
tower_cli.exceptions.JobFailure – When the job being monitored runs into failure.

relaunch(pk=None, **kwargs): Relaunch a stopped job resource.

Parameters

pk (int) – Primary key of the job resource to relaunch.
**kwargs – Keyword arguments used to look up job resource object to relaunch if pk is not provided.

Returns: A dictionary combining the JSON output of the relaunched job resource object, as well as an extra field “changed”, a flag indicating if the job resource object is status-changed as expected.
Return type: dict

status(pk=None, detail=False, **kwargs): Retrieve the current job status.

Parameters

pk (int) – Primary key of the resource to retrieve status from.
detail (bool) – Flag that if set, return the full JSON of the job resource rather than a status summary.
**kwargs – Keyword arguments used to look up resource object to retrieve status from if pk is not provided.

Returns: full loaded JSON of the specified unified job if detail flag is on; trimed JSON containing only “elapsed”, “failed” and “status” fields of the unified job if detail flag is off.
Return type: dict

wait(pk, parent_pk=None, min_interval=1, max_interval=30, timeout=None, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='ANSI_X3.4-1968'>, exit_on=['successful'], **kwargs): Wait for a job resource object to enter certain status.

Parameters

pk (int) – Primary key of the job resource object to wait.
parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be waited if pk is not set.
timeout (float) – Number in seconds after which this method will time out.
min_interval (float) – Minimum polling interval to request an update from Tower.
max_interval (float) – Maximum polling interval to request an update from Tower.
outfile (file) – Alternative file than stdout to write job status updates on.
exit_on (array) – Job resource object statuses to wait on.
**kwargs – Keyword arguments used to look up job resource object to wait if pk is not provided.

Returns: A dictionary combining the JSON output of the status-changed job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is status-changed as expected; “id”, an integer which is the primary key of the job resource object being status-changed.
Return type: dict
Raises

tower_cli.exceptions.Timeout – When wait time reaches time out.
tower_cli.exceptions.JobFailure – When the job being waited on runs into failure.

Credential Type¶

Description¶

This resource is used for managing credential type resources in Tower.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
description	String	The description field.	False	False	True	False
kind	Choices: ssh,vault,net,scm,cloud,insights	The type of credential type being added. Valid options are: ssh, vault, net, scm, cloud and insights. Note only cloud and net can be used for creating credential types.	False	False	True	True
managed_by_tower	bool	Indicating if the credential type is a tower built-in type.	True	False	True	False
inputs	structured_input	The inputs field.	False	False	True	False
injectors	structured_input	The injectors field.	False	False	True	False

API Specification¶

class tower_cli.resources.credential_type.Resource: A resource for credential types.

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(**kwargs): Create an object.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

Credential¶

Description¶

This resource is used for managing credential resources in Tower.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
description	String	The description field.	False	False	True	False
user	Resource user	The user field.	False	False	True	False
team	Resource team	The team field.	False	False	True	False
organization	Resource organization	The organization field.	False	False	True	False
credential_type	Resource credential_type	The credential_type field.	False	False	True	True
inputs	structured_input	The inputs field.	False	False	True	False

API Specification¶

class tower_cli.resources.credential.Resource: A resource for credentials.

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(**kwargs): Create an object.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

Group¶

Description¶

This resource is used for managing group resources in Tower. It can also associate/disassociate one group to/from another group.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
description	String	The description field.	False	False	True	False
inventory	Resource inventory	The inventory field.	False	False	True	True
variables	variables	Group variables, use “@” to get from file.	False	False	True	False

API Specification¶

class tower_cli.resources.group.Resource: A resource for groups.

associate(group, parent, **kwargs): Associate this group with the specified group.

Parameters

group (str) – Primary key or name of the child group to associate.
parent (str) – Primary key or name of the parent group to associate to.
inventory (str) – Primary key or name of the inventory the association should happen in.

Returns: Dictionary of only one key “changed”, which indicates whether the association succeeded.
Return type: dict

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(fail_on_found=False, force_on_exists=False, **kwargs): Create a group.

Parameters

parent (str) – Primary key or name of the group which will be the parent of created group.
fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict
Raises: tower_cli.exceptions.UsageError – When inventory is not provided in **kwargs and parent is not provided.

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

disassociate(group, parent, **kwargs): Disassociate this group with the specified group.

Parameters

group (str) – Primary key or name of the child group to disassociate.
parent (str) – Primary key or name of the parent group to disassociate from.
inventory (str) – Primary key or name of the inventory the disassociation should happen in.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociation succeeded.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(root=False, **kwargs): Retrieve a list of groups.

Parameters

root (bool) – Flag that if set, only root groups of a specific inventory will be listed.
parent (str) – Primary key or name of the group whose child groups will be listed.
all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict
Raises: tower_cli.exceptions.UsageError – When root flag is on and inventory is not present in **kwargs.

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

Host¶

Description¶

This resource is used for managing host resources in Tower. It can also associate/disassociate a group to/from a host.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
description	String	The description field.	False	False	True	False
inventory	Resource inventory	The inventory field.	False	False	True	True
enabled	bool	The enabled field.	False	False	True	False
variables	variables	Host variables, use “@” to get from file.	False	False	True	False
insights_system_id	String	The insights_system_id field.	False	False	True	False

API Specification¶

class tower_cli.resources.host.Resource: A resource for credentials.

associate(**kwargs): Associate a group with this host.

Parameters

host (str) – Primary key or name of the host to associate to.
group (str) – Primary key or name of the group to be associated.

Returns: Dictionary of only one key “changed”, which indicates whether the associate succeeded.
Return type: dict

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(**kwargs): Create an object.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

disassociate(**kwargs): Disassociate a group with this host.

Parameters

host (str) – Primary key or name of the host to disassociate to.
group (str) – Primary key or name of the group to be disassociated.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociate succeeded.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

insights(pk=None, **kwargs): List host insights.

Parameters

pk (int) – Primary key of the target host.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object of host insights.
Return type: dict

list(group=None, host_filter=None, **kwargs): Retrieve a list of hosts.

Parameters

group (str) – Primary key or name of the group whose hosts will be listed.
all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

list_facts(pk=None, **kwargs): List all available facts of the given host.

Parameters

pk (int) – Primary key of the target host.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object of all available facts of the given host.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

Instance Group¶

Description¶

This resource is used for managing instance group resources in Tower. Note since instance groups are read-only in Tower, only get and list methods are available for this resource.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	False	True	False
capacity	int	The capacity field.	False	False	True	False
consumed_capacity	int	The consumed_capacity field.	False	False	True	False

API Specification¶

class tower_cli.resources.instance_group.Resource: A resource for instance groups.

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

Instance¶

Description¶

This resource is used for managing instance resources in Tower. Note since instances are read-only in Tower, only get and list methods are available for this resource.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
uuid	String	The uuid field.	False	False	True	False
hostname	String	The hostname field.	False	False	True	False
version	String	The version field.	False	False	True	False
capacity	int	The capacity field.	False	False	True	False
consumed_capacity	int	The consumed_capacity field.	False	False	True	False

API Specification¶

class tower_cli.resources.instance.Resource: A resource for instances.

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

Inventory Script¶

Description¶

This resource is used for managing inventory script resources in Tower.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
description	String	The description field.	False	False	True	False
script	variables	Script code to fetch inventory, prefix with “@” to use contents of file for this field.	False	False	True	True
organization	Resource organization	The organization field.	False	False	True	True

API Specification¶

class tower_cli.resources.inventory_script.Resource: A resource for inventory scripts.

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(**kwargs): Create an object.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

Inventory Source¶

Description¶

This resource is used for managing and executing inventory sources via Tower. Note inventory updates are triggered via update method.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
description	String	The description field.	False	False	True	False
inventory	Resource inventory	The inventory field.	False	False	True	True
source	Choices: ,file,scm,ec2,vmware,gce,azure,azure_rm,openstack,satellite6,cloudforms,custom	The type of inventory source in use.	False	False	True	True
credential	Resource credential	The credential field.	False	False	True	False
source_vars	String	The source_vars field.	False	False	True	False
timeout	int	The timeout field (in seconds).	False	False	True	False
source_project	Resource project	Use project files as source for inventory.	False	False	True	False
source_path	String	File in SCM Project to use as source.	False	False	True	False
update_on_project_update	bool	The update_on_project_update field.	False	False	True	False
source_regions	String	The source_regions field.	False	False	True	False
instance_filters	String	The instance_filters field.	False	False	True	False
group_by	String	The group_by field.	False	False	True	False
source_script	Resource inventory_script	The source_script field.	False	False	True	False
overwrite	bool	The overwrite field.	False	False	True	False
overwrite_vars	bool	The overwrite_vars field.	False	False	True	False
update_on_launch	bool	The update_on_launch field.	False	False	True	False
update_cache_timeout	int	The update_cache_timeout field.	False	False	True	False

API Specification¶

class tower_cli.resources.inventory_source.Resource(*args, **kwargs): A resource for inventory sources.

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(**kwargs): Create an object.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

monitor(pk, parent_pk=None, timeout=None, interval=0.5, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='ANSI_X3.4-1968'>, **kwargs): Stream the standard output from a job run to stdout.

Parameters

pk (int) – Primary key of the job resource object to be monitored.
parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be monitored if pk is not set.
timeout (float) – Number in seconds after which this method will time out.
interval (float) – Polling interval to refresh content from Tower.
outfile (file) – Alternative file than stdout to write job stdout to.
**kwargs – Keyword arguments used to look up job resource object to monitor if pk is not provided.

Returns: A dictionary combining the JSON output of the finished job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is finished as expected; “id”, an integer which is the primary key of the job resource object being monitored.
Return type: dict
Raises

tower_cli.exceptions.Timeout – When monitor time reaches time out.
tower_cli.exceptions.JobFailure – When the job being monitored runs into failure.

status(pk, detail=False, **kwargs): Retrieve the current inventory update status.

Parameters

pk (int) – Primary key of the resource to retrieve status from.
detail (bool) – Flag that if set, return the full JSON of the job resource rather than a status summary.
**kwargs – Keyword arguments used to look up resource object to retrieve status from if pk is not provided.

Returns: full loaded JSON of the specified unified job if detail flag is on; trimed JSON containing only “elapsed”, “failed” and “status” fields of the unified job if detail flag is off.
Return type: dict

update(inventory_source, monitor=False, wait=False, timeout=None, **kwargs): Update the given inventory source.

Parameters

inventory_source (str) – Primary key or name of the inventory source to be updated.
monitor (bool) – Flag that if set, immediately calls monitor on the newly launched inventory update rather than exiting with a success.
wait (bool) – Flag that if set, monitor the status of the inventory update, but do not print while it is in progress.
timeout (int) – If provided with monitor flag set, this attempt will time out after the given number of seconds.
**kwargs – Fields used to override underlyingl inventory source fields when creating and launching an inventory update.

Returns: Result of subsequent monitor call if monitor flag is on; Result of subsequent wait call if wait flag is on; dictionary of “status” if none of the two flags are on.
Return type: dict
Raises: tower_cli.exceptions.BadRequest – When the inventory source cannot be updated.

wait(pk, parent_pk=None, min_interval=1, max_interval=30, timeout=None, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='ANSI_X3.4-1968'>, exit_on=['successful'], **kwargs): Wait for a job resource object to enter certain status.

Parameters

pk (int) – Primary key of the job resource object to wait.
parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be waited if pk is not set.
timeout (float) – Number in seconds after which this method will time out.
min_interval (float) – Minimum polling interval to request an update from Tower.
max_interval (float) – Maximum polling interval to request an update from Tower.
outfile (file) – Alternative file than stdout to write job status updates on.
exit_on (array) – Job resource object statuses to wait on.
**kwargs – Keyword arguments used to look up job resource object to wait if pk is not provided.

Returns: A dictionary combining the JSON output of the status-changed job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is status-changed as expected; “id”, an integer which is the primary key of the job resource object being status-changed.
Return type: dict
Raises

tower_cli.exceptions.Timeout – When wait time reaches time out.
tower_cli.exceptions.JobFailure – When the job being waited on runs into failure.

Inventory Update¶

Description¶

This resource is used for managing and executing inventory updates via Tower.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
inventory_source	Resource inventory_source	The inventory_source field.	False	False	True	True
name	String	The name field.	True	False	True	False
launch_type	Choices: manual,relaunch,relaunch,callback,scheduled,dependency,workflow,sync,scm	The launch_type field.	True	False	True	True
status	Choices: new,pending,waiting,running,successful,failed,error,canceled	The status field.	True	False	True	True
job_explanation	String	The job_explanation field.	True	False	True	False
created	String	The created field.	True	False	True	False
elapsed	String	The elapsed field.	True	False	True	False
source	Choices: ,file,scm,ec2,vmware,gce,azure,azure_rm,openstack,satellite6,cloudforms,custom	The source field.	False	False	True	True

API Specification¶

class tower_cli.resources.inventory_update.Resource(*args, **kwargs): A resource for inventory source updates.

cancel(pk=None, fail_if_not_running=False, **kwargs): Cancel a currently running job.

Parameters

pk (int) – Primary key of the job resource to restart.
fail_if_not_running (bool) – Flag that if set, raise exception if the job resource cannot be canceled.
**kwargs – Keyword arguments used to look up job resource object to restart if pk is not provided.

Returns: A dictionary of two keys: “status”, which is “canceled”, and “changed”, which indicates if the job resource has been successfully canceled.
Return type: dict
Raises: tower_cli.exceptions.TowerCLIError – When the job resource cannot be canceled and fail_if_not_running flag is on.

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

monitor(pk, parent_pk=None, timeout=None, interval=0.5, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='ANSI_X3.4-1968'>, **kwargs): Stream the standard output from a job run to stdout.

Parameters

pk (int) – Primary key of the job resource object to be monitored.
parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be monitored if pk is not set.
timeout (float) – Number in seconds after which this method will time out.
interval (float) – Polling interval to refresh content from Tower.
outfile (file) – Alternative file than stdout to write job stdout to.
**kwargs – Keyword arguments used to look up job resource object to monitor if pk is not provided.

Returns: A dictionary combining the JSON output of the finished job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is finished as expected; “id”, an integer which is the primary key of the job resource object being monitored.
Return type: dict
Raises

tower_cli.exceptions.Timeout – When monitor time reaches time out.
tower_cli.exceptions.JobFailure – When the job being monitored runs into failure.

relaunch(pk=None, **kwargs): Relaunch a stopped job resource.

Parameters

pk (int) – Primary key of the job resource to relaunch.
**kwargs – Keyword arguments used to look up job resource object to relaunch if pk is not provided.

Returns: A dictionary combining the JSON output of the relaunched job resource object, as well as an extra field “changed”, a flag indicating if the job resource object is status-changed as expected.
Return type: dict

status(pk=None, detail=False, **kwargs): Retrieve the current job status.

Parameters

pk (int) – Primary key of the resource to retrieve status from.
detail (bool) – Flag that if set, return the full JSON of the job resource rather than a status summary.
**kwargs – Keyword arguments used to look up resource object to retrieve status from if pk is not provided.

Returns: full loaded JSON of the specified unified job if detail flag is on; trimed JSON containing only “elapsed”, “failed” and “status” fields of the unified job if detail flag is off.
Return type: dict

wait(pk, parent_pk=None, min_interval=1, max_interval=30, timeout=None, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='ANSI_X3.4-1968'>, exit_on=['successful'], **kwargs): Wait for a job resource object to enter certain status.

Parameters

pk (int) – Primary key of the job resource object to wait.
parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be waited if pk is not set.
timeout (float) – Number in seconds after which this method will time out.
min_interval (float) – Minimum polling interval to request an update from Tower.
max_interval (float) – Maximum polling interval to request an update from Tower.
outfile (file) – Alternative file than stdout to write job status updates on.
exit_on (array) – Job resource object statuses to wait on.
**kwargs – Keyword arguments used to look up job resource object to wait if pk is not provided.

Returns: A dictionary combining the JSON output of the status-changed job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is status-changed as expected; “id”, an integer which is the primary key of the job resource object being status-changed.
Return type: dict
Raises

tower_cli.exceptions.Timeout – When wait time reaches time out.
tower_cli.exceptions.JobFailure – When the job being waited on runs into failure.

Inventory¶

Description¶

This resource is used for managing inventory resources in Tower.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
description	String	The description field.	False	False	True	False
organization	Resource organization	The organization field.	False	False	True	True
variables	variables	Inventory variables, use “@” to get from file.	False	False	True	False
kind	Choices: ,smart	The kind field. Cannot be modified after created.	False	False	True	False
host_filter	String	The host_filter field. Only useful when kind=smart.	False	False	True	False
insights_credential	Resource credential	The insights_credential field.	False	False	True	False

API Specification¶

class tower_cli.resources.inventory.Resource: A resource for inventories.

associate_ig(**kwargs): Associate an ig with this inventory.

Parameters

inventory (str) – Primary key or name of the inventory to associate to.
instance_group (str) – Primary key or name of the instance_group to be associated.

Returns: Dictionary of only one key “changed”, which indicates whether the associate succeeded.
Return type: dict

batch_update(pk=None, **kwargs): Update all related inventory sources of the given inventory.

Parameters

pk (int) – Primary key of the given inventory.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object of update status of the given inventory.
Return type: dict

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(**kwargs): Create an object.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

disassociate_ig(**kwargs): Disassociate an ig with this inventory.

Parameters

inventory (str) – Primary key or name of the inventory to disassociate to.
instance_group (str) – Primary key or name of the instance_group to be disassociated.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociate succeeded.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

Job Template¶

Description¶

This resource is used for managing job template resources in Tower. It is also responsible to associate/disassociate labels and notification templates to/from an existing job template. There is yet another custom command, survey, used for getting survey specification of a job template.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
description	String	The description field.	False	False	True	False
job_type	Choices: run,check	The job_type field.	False	False	True	False
inventory	Resource inventory	The inventory field.	False	False	True	False
project	Resource project	The project field.	False	False	True	True
playbook	String	The playbook field.	False	False	True	True
credential	Resource credential	The credential field.	False	False	True	False
vault_credential	Resource credential	The vault_credential field.	False	False	True	False
forks	int	The forks field.	False	False	True	False
limit	String	The limit field.	False	False	True	False
verbosity	mapped_choice	The verbosity field.	False	False	True	False
extra_vars	variables	Extra variables used by Ansible in YAML or key=value format. Use @ to get YAML from a file.	False	False	True	False
job_tags	String	The job_tags field.	False	False	True	False
force_handlers	bool	The force_handlers field.	False	False	True	False
skip_tags	String	The skip_tags field.	False	False	True	False
start_at_task	String	The start_at_task field.	False	False	True	False
timeout	int	The amount of time (in seconds) to run before the task is canceled.	False	False	True	False
use_fact_cache	bool	If enabled, Tower will act as an Ansible Fact Cache Plugin; persisting facts at the end of a playbook run to the database and caching facts for use by Ansible.	False	False	True	False
host_config_key	String	Allow Provisioning Callbacks using this host config key	False	False	True	False
ask_diff_mode_on_launch	bool	Ask diff mode on launch.	False	False	True	False
ask_variables_on_launch	bool	Prompt user for extra_vars on launch.	False	False	True	False
ask_limit_on_launch	bool	Prompt user for host limits on launch.	False	False	True	False
ask_tags_on_launch	bool	Prompt user for job tags on launch.	False	False	True	False
ask_skip_tags_on_launch	bool	Prompt user for tags to skip on launch.	False	False	True	False
ask_job_type_on_launch	bool	Prompt user for job type on launch.	False	False	True	False
ask_verbosity_on_launch	bool	Prompt user for verbosity on launch.	False	False	True	False
ask_inventory_on_launch	bool	Prompt user for inventory on launch.	False	False	True	False
ask_credential_on_launch	bool	Prompt user for machine credential on launch.	False	False	True	False
survey_enabled	bool	Prompt user for job type on launch.	False	False	True	False
become_enabled	bool	The become_enabled field.	False	False	True	False
diff_mode	bool	If enabled, textual changes made to any templated files on the host are shown in the standard output.	False	False	True	False
allow_simultaneous	bool	The allow_simultaneous field.	False	False	True	False
survey_spec	variables	On write commands, perform extra POST to the survey_spec endpoint.	False	False	True	False

API Specification¶

class tower_cli.resources.job_template.Resource: A resource for job templates.

associate_credential(job_template, credential): Associate a credential with this job template.

Parameters

job_template (str) – The job template to associate to.
credential (str) – The credential to be associated.

Returns: Dictionary of only one key “changed”, which indicates whether the association succeeded.
Return type: dict

associate_ig(**kwargs): Associate an ig with this job_template.

Parameters

job_template (str) – Primary key or name of the job_template to associate to.
instance_group (str) – Primary key or name of the instance_group to be associated.

Returns: Dictionary of only one key “changed”, which indicates whether the associate succeeded.
Return type: dict

associate_label(**kwargs): Associate a label with this job_template.

Parameters

job_template (str) – Primary key or name of the job_template to associate to.
label (str) – Primary key or name of the label to be associated.

Returns: Dictionary of only one key “changed”, which indicates whether the associate succeeded.
Return type: dict

associate_notification_template(job_template, notification_template, status): Associate a notification template from this job template.

Parameters

job_template (str) – The job template to associate to.
notification_template (str) – The notification template to be associated.
status (str) – type of notification this notification template should be associated to.

Returns: Dictionary of only one key “changed”, which indicates whether the association succeeded.
Return type: dict

callback(pk=None, host_config_key='', extra_vars=None): Contact Tower and request a provisioning callback using this job template.

Parameters

pk (int) – Primary key of the job template to run provisioning callback against.
host_config_key (str) – Key string used to authenticate the callback host.
extra_vars (array of str) – Extra variables that are passed to provisioning callback.

Returns: A dictionary of a single key “changed”, which indicates whether the provisioning callback is successful.
Return type: dict

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(**kwargs): Create an object.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

disassociate_credential(job_template, credential): Disassociate a credential from this job template.

Parameters

job_template (str) – The job template to disassociate fom.
credential (str) – The credential to be disassociated.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociation succeeded.
Return type: dict

disassociate_ig(**kwargs): Disassociate an ig with this job_template.

Parameters

job_template (str) – Primary key or name of the job_template to disassociate to.
instance_group (str) – Primary key or name of the instance_group to be disassociated.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociate succeeded.
Return type: dict

disassociate_label(**kwargs): Disassociate a label with this job_template.

Parameters

job_template (str) – Primary key or name of the job_template to disassociate to.
label (str) – Primary key or name of the label to be disassociated.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociate succeeded.
Return type: dict

disassociate_notification_template(job_template, notification_template, status): Disassociate a notification template from this job template.

Parameters

job_template (str) – The job template to disassociate from.
notification_template (str) – The notification template to be disassociated.
status (str) – type of notification this notification template should be disassociated from.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociation succeeded.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

survey(pk=None, **kwargs): Get the survey specification of a resource object.

Parameters

pk (int) – Primary key of the resource to retrieve survey from. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve survey if pk is not provided.

Returns: loaded JSON of the retrieved survey specification of the resource object.
Return type: dict

Job¶

Description¶

This resource is used for managing jobs and launching job templates via Tower. Note for historical purposes, launching a job template is linked to job, rather than job template.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
job_template	Resource job_template	The job_template field.	False	False	True	False
job_explanation	String	The job_explanation field.	True	False	True	False
created	String	The created field.	False	False	True	False
status	String	The status field.	False	False	True	False
elapsed	String	The elapsed field.	False	False	True	False

API Specification¶

class tower_cli.resources.job.Resource(*args, **kwargs): A resource for jobs.
This resource has ordinary list and get methods, but it does not have create or modify. Instead of being created, a job is launched.

cancel(pk=None, fail_if_not_running=False, **kwargs): Cancel a currently running job.

Parameters

pk (int) – Primary key of the job resource to restart.
fail_if_not_running (bool) – Flag that if set, raise exception if the job resource cannot be canceled.
**kwargs – Keyword arguments used to look up job resource object to restart if pk is not provided.

Returns: A dictionary of two keys: “status”, which is “canceled”, and “changed”, which indicates if the job resource has been successfully canceled.
Return type: dict
Raises: tower_cli.exceptions.TowerCLIError – When the job resource cannot be canceled and fail_if_not_running flag is on.

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

launch(job_template=None, monitor=False, wait=False, timeout=None, no_input=True, extra_vars=None, **kwargs): Launch a new job based on a job template.

Parameters

job_template (str) – Primary key or name of the job template to launch new job.
monitor (bool) – Flag that if set, immediately calls monitor on the newly launched job rather than exiting with a success.
wait (bool) – Flag that if set, monitor the status of the job, but do not print while job is in progress.
timeout (int) – If provided with monitor flag set, this attempt will time out after the given number of seconds.
no_input (bool) – Flag that if set, suppress any requests for input.
extra_vars (array of strings) – yaml formatted texts that contains extra variables to pass on.
diff_mode (bool) – Specify diff mode for job template to run.
limit (str) – Specify host limit for job template to run.
tags (str) – Specify tagged actions in the playbook to run.
skip_tags (str) – Specify tagged actions in the playbook to omit.
job_type (str) – Specify job type for job template to run.
verbosity (int) – Specify verbosity of the playbook run.
inventory (str) – Specify machine credential for job template to run.
credential (str) – Specify machine credential for job template to run.

Returns: Result of subsequent monitor call if monitor flag is on; Result of subsequent wait call if wait flag is on; Result of subsequent status call if none of the two flags are on.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

monitor(pk, parent_pk=None, timeout=None, interval=0.5, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='ANSI_X3.4-1968'>, **kwargs): Stream the standard output from a job run to stdout.

Parameters

pk (int) – Primary key of the job resource object to be monitored.
parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be monitored if pk is not set.
timeout (float) – Number in seconds after which this method will time out.
interval (float) – Polling interval to refresh content from Tower.
outfile (file) – Alternative file than stdout to write job stdout to.
**kwargs – Keyword arguments used to look up job resource object to monitor if pk is not provided.

Returns: A dictionary combining the JSON output of the finished job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is finished as expected; “id”, an integer which is the primary key of the job resource object being monitored.
Return type: dict
Raises

tower_cli.exceptions.Timeout – When monitor time reaches time out.
tower_cli.exceptions.JobFailure – When the job being monitored runs into failure.

relaunch(pk=None, **kwargs): Relaunch a stopped job resource.

Parameters

pk (int) – Primary key of the job resource to relaunch.
**kwargs – Keyword arguments used to look up job resource object to relaunch if pk is not provided.

Returns: A dictionary combining the JSON output of the relaunched job resource object, as well as an extra field “changed”, a flag indicating if the job resource object is status-changed as expected.
Return type: dict

status(pk=None, detail=False, **kwargs): Retrieve the current job status.

Parameters

pk (int) – Primary key of the resource to retrieve status from.
detail (bool) – Flag that if set, return the full JSON of the job resource rather than a status summary.
**kwargs – Keyword arguments used to look up resource object to retrieve status from if pk is not provided.

Returns: full loaded JSON of the specified unified job if detail flag is on; trimed JSON containing only “elapsed”, “failed” and “status” fields of the unified job if detail flag is off.
Return type: dict

stdout(pk, start_line=None, end_line=None, **kwargs)

wait(pk, parent_pk=None, min_interval=1, max_interval=30, timeout=None, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='ANSI_X3.4-1968'>, exit_on=['successful'], **kwargs): Wait for a job resource object to enter certain status.

Parameters

pk (int) – Primary key of the job resource object to wait.
parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be waited if pk is not set.
timeout (float) – Number in seconds after which this method will time out.
min_interval (float) – Minimum polling interval to request an update from Tower.
max_interval (float) – Maximum polling interval to request an update from Tower.
outfile (file) – Alternative file than stdout to write job status updates on.
exit_on (array) – Job resource object statuses to wait on.
**kwargs – Keyword arguments used to look up job resource object to wait if pk is not provided.

Returns: A dictionary combining the JSON output of the status-changed job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is status-changed as expected; “id”, an integer which is the primary key of the job resource object being status-changed.
Return type: dict
Raises

tower_cli.exceptions.Timeout – When wait time reaches time out.
tower_cli.exceptions.JobFailure – When the job being waited on runs into failure.

Label¶

Description¶

This resource is used for managing label resources in Tower.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
organization	Resource organization	The organization field.	False	False	True	True

API Specification¶

class tower_cli.resources.label.Resource: A resource for labels.

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(fail_on_found=False, force_on_exists=False, **kwargs): Create a label.

Parameters

job_template (str) – Primary key or name of the job template for the created label to associate to.
fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict
Raises: tower_cli.exceptions.TowerCLIError – When the label already exists and fail_on_found flag is on.

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

Workflow Node¶

Description¶

This resource is used for managing workflow job template nodes in Tower. It can also used for building workflow topology by associating/disassociating nodes.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
workflow_job_template	Resource workflow	The workflow_job_template field.	False	False	True	True
unified_job_template	String	The unified_job_template field.	False	False	True	False
inventory	Resource inventory	The inventory field.	False	False	True	False
credential	Resource credential	The credential field.	False	False	True	False
job_type	String	The job_type field.	False	False	True	False
job_tags	String	The job_tags field.	False	False	True	False
skip_tags	String	The skip_tags field.	False	False	True	False
limit	String	The limit field.	False	False	True	False

API Specification¶

class tower_cli.resources.node.Resource: A resource for workflow nodes.

associate_always_node(parent, child=None, **kwargs): Add a node to always run after the parent is finished.

Parameters

parent (int) – Primary key of parent node to associate always node to.
child (int) – Primary key of child node to be associated.
**kwargs – Fields used to create child node if child is not provided.

Returns: Dictionary of only one key “changed”, which indicates whether the association succeeded.
Return type: dict

associate_failure_node(parent, child=None, **kwargs): Add a node to run on failure.

Parameters

parent (int) – Primary key of parent node to associate failure node to.
child (int) – Primary key of child node to be associated.
**kwargs – Fields used to create child node if child is not provided.

Returns: Dictionary of only one key “changed”, which indicates whether the association succeeded.
Return type: dict

associate_success_node(parent, child=None, **kwargs): Add a node to run on success.

Parameters

parent (int) – Primary key of parent node to associate success node to.
child (int) – Primary key of child node to be associated.
**kwargs – Fields used to create child node if child is not provided.

Returns: Dictionary of only one key “changed”, which indicates whether the association succeeded.
Return type: dict

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(**kwargs): Create an object.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

disassociate_always_node(parent, child): Remove an always node link.

Parameters

parent (int) – Primary key of parent node to disassociate always node from.
child (int) – Primary key of child node to be disassociated.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociation succeeded.
Return type: dict

disassociate_failure_node(parent, child): Remove a failure node link.

Parameters

parent (int) – Primary key of parent node to disassociate failure node from.
child (int) – Primary key of child node to be disassociated.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociation succeeded.
Return type: dict

disassociate_success_node(parent, child): Remove success node.

Parameters

parent (int) – Primary key of parent node to disassociate success node from.
child (int) – Primary key of child node to be disassociated.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociation succeeded.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

Notification Template¶

Description¶

This resource is used for managing notification templates in Tower. Note most resource fields, like username and host are effective based on notification_type. For example, providing service_key when creating an email notification template is not effective as it will be discarded.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
description	String	The description field.	False	False	True	False
organization	Resource organization	The organization field.	False	False	True	False
notification_type	Choices: email,slack,twilio,pagerduty,hipchat,webhook,irc	The notification_type field.	False	False	True	True
notification_configuration	file	The notification configuration field. Note providing this field would disable all notification-configuration-related fields.	False	False	True	False
username	String	[email]The username.	False	False	True	False
sender	String	[email]The sender.	False	False	True	False
recipients	String	[email]The recipients.	False	False	True	False
use_tls	BOOL	[email]The tls trigger.	False	False	True	False
host	String	[email]The host.	False	False	True	False
use_ssl	BOOL	[email/irc]The ssl trigger.	False	False	True	False
password	String	[email/irc]The password.	False	False	True	False
port	INT	[email/irc]The email port.	False	False	True	False
channels	String	[slack]The channel.	False	False	True	False
token	String	[slack/pagerduty/hipchat]The token.	False	False	True	False
account_token	String	[twilio]The account token.	False	False	True	False
from_number	String	[twilio]The source phone number.	False	False	True	False
to_numbers	String	[twilio]The destination SMS numbers.	False	False	True	False
account_sid	String	[twilioThe account sid.	False	False	True	False
subdomain	String	[pagerduty]The subdomain.	False	False	True	False
service_key	String	[pagerduty]The API service/integration key.	False	False	True	False
client_name	String	[pagerduty]The client identifier.	False	False	True	False
message_from	String	[hipchat]The label to be shown with notification.	False	False	True	False
api_url	String	[hipchat]The api url.	False	False	True	False
color	Choices: yellow,green,red,purple,gray,random	[hipchat]The notification color.	False	False	True	False
rooms	String	[hipchat]Rooms to send notification to. Use multiple flags to send to multiple rooms, ex –rooms=A –rooms=B	False	False	True	False
notify	String	[hipchat]The notify channel trigger.	False	False	True	False
url	String	[webhook]The target URL.	False	False	True	False
headers	file	[webhook]The http headers.	False	False	True	False
server	String	[irc]Server address.	False	False	True	False
nickname	String	[irc]The irc nick.	False	False	True	False
target	String	[irc]The distination channels or users.	False	False	True	False

API Specification¶

class tower_cli.resources.notification_template.Resource: A resource for notification templates.

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(fail_on_found=False, force_on_exists=False, **kwargs): Create an object.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

Organization¶

Description¶

This resource is used for managing organization resources in Tower. It can also perform some associations/disassociations.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
description	String	The description field.	False	False	True	False

API Specification¶

class tower_cli.resources.organization.Resource

associate(**kwargs): Associate a user with this organization.

Parameters

organization (str) – Primary key or name of the organization to associate to.
user (str) – Primary key or name of the user to be associated.

Returns: Dictionary of only one key “changed”, which indicates whether the associate succeeded.
Return type: dict

associate_admin(**kwargs): Associate an admin with this organization.

Parameters

organization (str) – Primary key or name of the organization to associate to.
user (str) – Primary key or name of the user to be associated.

Returns: Dictionary of only one key “changed”, which indicates whether the associate succeeded.
Return type: dict

associate_ig(**kwargs): Associate an ig with this organization.

Parameters

organization (str) – Primary key or name of the organization to associate to.
instance_group (str) – Primary key or name of the instance_group to be associated.

Returns: Dictionary of only one key “changed”, which indicates whether the associate succeeded.
Return type: dict

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(**kwargs): Create an object.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

disassociate(**kwargs): Disassociate a user with this organization.

Parameters

organization (str) – Primary key or name of the organization to disassociate to.
user (str) – Primary key or name of the user to be disassociated.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociate succeeded.
Return type: dict

disassociate_admin(**kwargs): Disassociate an admin with this organization.

Parameters

organization (str) – Primary key or name of the organization to disassociate to.
user (str) – Primary key or name of the user to be disassociated.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociate succeeded.
Return type: dict

disassociate_ig(**kwargs): Disassociate an ig with this organization.

Parameters

organization (str) – Primary key or name of the organization to disassociate to.
instance_group (str) – Primary key or name of the instance_group to be disassociated.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociate succeeded.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

Project¶

Description¶

This resource is used for managing and executing projects via Tower. Note project updates are triggered via update method.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
description	String	The description field.	False	False	True	False
organization	Resource organization	The organization field.	False	False	True	False
scm_type	mapped_choice	The scm_type field.	False	False	True	True
scm_url	String	The scm_url field.	False	False	True	False
local_path	String	For manual projects, the server playbook directory name.	False	False	True	False
scm_branch	String	The scm_branch field.	False	False	True	False
scm_credential	Resource credential	The scm_credential field.	False	False	True	False
scm_clean	bool	The scm_clean field.	False	False	True	False
scm_delete_on_update	bool	The scm_delete_on_update field.	False	False	True	False
scm_update_on_launch	bool	The scm_update_on_launch field.	False	False	True	False
scm_update_cache_timeout	int	The scm_update_cache_timeout field.	False	False	True	False
job_timeout	int	The timeout field (in seconds).	False	False	True	False

API Specification¶

class tower_cli.resources.project.Resource(*args, **kwargs): A resource for projects.

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(organization=None, monitor=False, wait=False, timeout=None, fail_on_found=False, force_on_exists=False, **kwargs): Create a project and, if related flags are set, monitor or wait the triggered initial project update.

Parameters

monitor (bool) – Flag that if set, immediately calls monitor on the newly triggered project update rather than exiting with a success.
wait (bool) – Flag that if set, monitor the status of the triggered project update, but do not print while it is in progress.
timeout (bool) – If provided with monitor flag set, this attempt will time out after the given number of seconds.
fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing project.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

monitor(pk, parent_pk=None, timeout=None, interval=0.5, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='ANSI_X3.4-1968'>, **kwargs): Stream the standard output from a job run to stdout.

Parameters

pk (int) – Primary key of the job resource object to be monitored.
parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be monitored if pk is not set.
timeout (float) – Number in seconds after which this method will time out.
interval (float) – Polling interval to refresh content from Tower.
outfile (file) – Alternative file than stdout to write job stdout to.
**kwargs – Keyword arguments used to look up job resource object to monitor if pk is not provided.

Returns: A dictionary combining the JSON output of the finished job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is finished as expected; “id”, an integer which is the primary key of the job resource object being monitored.
Return type: dict
Raises

tower_cli.exceptions.Timeout – When monitor time reaches time out.
tower_cli.exceptions.JobFailure – When the job being monitored runs into failure.

status(pk=None, detail=False, **kwargs): Print the status of the most recent update.

Parameters

pk (int) – Primary key of the resource to retrieve status from.
detail (bool) – Flag that if set, return the full JSON of the job resource rather than a status summary.
**kwargs – Keyword arguments used to look up resource object to retrieve status from if pk is not provided.

Returns: full loaded JSON of the specified unified job if detail flag is on; trimed JSON containing only “elapsed”, “failed” and “status” fields of the unified job if detail flag is off.
Return type: dict

stdout(pk, start_line=None, end_line=None, **kwargs)

update(pk=None, create_on_missing=False, monitor=False, wait=False, timeout=None, name=None, organization=None): Update the given project.

Parameters

pk (int) – Primary key of the project to be updated.
monitor (bool) – Flag that if set, immediately calls monitor on the newly launched project update rather than exiting with a success.
wait (bool) – Flag that if set, monitor the status of the project update, but do not print while it is in progress.
timeout (int) – If provided with monitor flag set, this attempt will time out after the given number of seconds.
name (str) – Name of the project to be updated if pk is not set.
organization (str) – Primary key or name of the organization the project to be updated belonging to if pk is not set.

Returns: Result of subsequent monitor call if monitor flag is on; Result of subsequent wait call if wait flag is on; dictionary of “status” if none of the two flags are on.
Return type: dict
Raises: tower_cli.exceptions.CannotStartJob – When the project cannot be updated.

wait(pk, parent_pk=None, min_interval=1, max_interval=30, timeout=None, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='ANSI_X3.4-1968'>, exit_on=['successful'], **kwargs): Wait for a job resource object to enter certain status.

Parameters

pk (int) – Primary key of the job resource object to wait.
parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be waited if pk is not set.
timeout (float) – Number in seconds after which this method will time out.
min_interval (float) – Minimum polling interval to request an update from Tower.
max_interval (float) – Maximum polling interval to request an update from Tower.
outfile (file) – Alternative file than stdout to write job status updates on.
exit_on (array) – Job resource object statuses to wait on.
**kwargs – Keyword arguments used to look up job resource object to wait if pk is not provided.

Returns: A dictionary combining the JSON output of the status-changed job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is status-changed as expected; “id”, an integer which is the primary key of the job resource object being status-changed.
Return type: dict
Raises

tower_cli.exceptions.Timeout – When wait time reaches time out.
tower_cli.exceptions.JobFailure – When the job being waited on runs into failure.

Project Update¶

Description¶

This resource is used for managing and executing project updates via Tower.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
project	Resource project	The project field.	False	False	True	True
name	String	The name field.	True	False	True	False
launch_type	Choices: manual,relaunch,relaunch,callback,scheduled,dependency,workflow,sync,scm	The launch_type field.	True	False	True	True
status	Choices: new,pending,waiting,running,successful,failed,error,canceled	The status field.	True	False	True	True
job_type	Choices: run,check	The job_type field.	True	False	True	True
job_explanation	String	The job_explanation field.	True	False	True	False
created	String	The created field.	True	False	True	False
elapsed	String	The elapsed field.	True	False	True	False
scm_type	mapped_choice	The scm_type field.	False	False	True	True

API Specification¶

class tower_cli.resources.project_update.Resource(*args, **kwargs): A resource for project updates.

cancel(pk=None, fail_if_not_running=False, **kwargs): Cancel a currently running job.

Parameters

pk (int) – Primary key of the job resource to restart.
fail_if_not_running (bool) – Flag that if set, raise exception if the job resource cannot be canceled.
**kwargs – Keyword arguments used to look up job resource object to restart if pk is not provided.

Returns: A dictionary of two keys: “status”, which is “canceled”, and “changed”, which indicates if the job resource has been successfully canceled.
Return type: dict
Raises: tower_cli.exceptions.TowerCLIError – When the job resource cannot be canceled and fail_if_not_running flag is on.

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

monitor(pk, parent_pk=None, timeout=None, interval=0.5, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='ANSI_X3.4-1968'>, **kwargs): Stream the standard output from a job run to stdout.

Parameters

pk (int) – Primary key of the job resource object to be monitored.
parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be monitored if pk is not set.
timeout (float) – Number in seconds after which this method will time out.
interval (float) – Polling interval to refresh content from Tower.
outfile (file) – Alternative file than stdout to write job stdout to.
**kwargs – Keyword arguments used to look up job resource object to monitor if pk is not provided.

Returns: A dictionary combining the JSON output of the finished job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is finished as expected; “id”, an integer which is the primary key of the job resource object being monitored.
Return type: dict
Raises

tower_cli.exceptions.Timeout – When monitor time reaches time out.
tower_cli.exceptions.JobFailure – When the job being monitored runs into failure.

relaunch(pk=None, **kwargs): Relaunch a stopped job resource.

Parameters

pk (int) – Primary key of the job resource to relaunch.
**kwargs – Keyword arguments used to look up job resource object to relaunch if pk is not provided.

Returns: A dictionary combining the JSON output of the relaunched job resource object, as well as an extra field “changed”, a flag indicating if the job resource object is status-changed as expected.
Return type: dict

status(pk=None, detail=False, **kwargs): Retrieve the current job status.

Parameters

pk (int) – Primary key of the resource to retrieve status from.
detail (bool) – Flag that if set, return the full JSON of the job resource rather than a status summary.
**kwargs – Keyword arguments used to look up resource object to retrieve status from if pk is not provided.

Returns: full loaded JSON of the specified unified job if detail flag is on; trimed JSON containing only “elapsed”, “failed” and “status” fields of the unified job if detail flag is off.
Return type: dict

wait(pk, parent_pk=None, min_interval=1, max_interval=30, timeout=None, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='ANSI_X3.4-1968'>, exit_on=['successful'], **kwargs): Wait for a job resource object to enter certain status.

Parameters

pk (int) – Primary key of the job resource object to wait.
parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be waited if pk is not set.
timeout (float) – Number in seconds after which this method will time out.
min_interval (float) – Minimum polling interval to request an update from Tower.
max_interval (float) – Maximum polling interval to request an update from Tower.
outfile (file) – Alternative file than stdout to write job status updates on.
exit_on (array) – Job resource object statuses to wait on.
**kwargs – Keyword arguments used to look up job resource object to wait if pk is not provided.

Returns: A dictionary combining the JSON output of the status-changed job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is status-changed as expected; “id”, an integer which is the primary key of the job resource object being status-changed.
Return type: dict
Raises

tower_cli.exceptions.Timeout – When wait time reaches time out.
tower_cli.exceptions.JobFailure – When the job being waited on runs into failure.

RBAC Role¶

Description¶

This resource is used for managing RBAC roles in Tower. More importantly, it can be used for granting roles to and revoke roles from a user or team.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
user	Resource user	The user field.	False	False	True	False
team	Resource team	The team that receives the permissions specified by the role.	False	False	True	False
type	Choices: admin,read,member,execute,adhoc,update,use,auditor	The type of permission that the role controls.	False	False	True	False
resource_name	String	The resource_name field.	False	False	True	False
resource_type	String	The resource_type field.	False	False	True	False
target_team	Resource team	The team that the role acts on.	False	False	True	False
inventory	Resource inventory	The inventory field.	False	False	True	False
job_template	Resource job_template	The job_template field.	False	False	True	False
credential	Resource credential	The credential field.	False	False	True	False
organization	Resource organization	The organization field.	False	False	True	False
project	Resource project	The project field.	False	False	True	False
workflow	Resource workflow	The workflow field.	False	False	True	False

API Specification¶

class tower_cli.resources.role.Resource: A resource for managing roles.
This resource has ordinary list and get methods, but it roles can not be created or edited, instead, they are automatically generated along with the connected resource.

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

grant(fail_on_found=False, **kwargs): Add a user or a team to a role. Required information: * Type of the role. * Resource of the role, inventory, credential, or any other. * A user or a team to add to the role.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if a user/team already has the role.
**kwargs – The user to be associated and the role to associate.

Returns: parsed JSON of role grant.
Return type: dict

list(**kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

revoke(fail_on_found=False, **kwargs): Remove a user or a team from a role. Required information: * Type of the role. * Resource of the role, inventory, credential, or any other. * A user or a team to add to the role.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if a user/team dose not have the role.
**kwargs – The user to be disassociated and the role to disassociate.

Returns: parsed JSON of role revoke.
Return type: dict

Schedule¶

Description¶

This resource is used for managing schedule resources in Tower.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
description	String	The description field.	False	False	True	False
job_template	Resource job_template	The job_template field.	False	False	True	False
inventory_source	Resource inventory_source	The inventory_source field.	False	False	True	False
project	Resource project	The project field.	False	False	True	False
unified_job_template	int	Integer used to display unified job template in result, Do not use it for create/modify.	False	False	True	False
enabled	BOOL	Whether this schedule will be used.	False	False	True	False
rrule	String	Schedule rules specifications which is less than 255 characters.	False	False	True	False
extra_data	variables	Extra data for schedule rules in the form of a .json file.	False	False	True	False

API Specification¶

class tower_cli.resources.schedule.Resource: A resource for schedules.

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(*args, **kwargs): Create an object.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, *args, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

get(pk=None, *args, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(*args, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(pk=None, *args, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

Tower Configuration¶

Description¶

This resource is used for managing tower configurations in Tower.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
value	variables	The value field.	False	False	True	True

API Specification¶

class tower_cli.resources.setting.Resource: A resource for Tower configurations.

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

get(pk): Return one and exactly one Tower setting.

Parameters: pk (int) – Primary key of the Tower setting to retrieve
Returns: loaded JSON of the retrieved Tower setting object.
Return type: dict
Raises: tower_cli.exceptions.NotFound – When no specified Tower setting exists.

list(**kwargs): Retrieve a list of Tower settings.

Parameters

category (str) – The category slug in which to look up indevidual settings.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(setting, value): Modify an already existing Tower setting.

Parameters

setting (str) – The name of the Tower setting to be modified.
value (str) – The new value of the Tower setting.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

Team¶

Description¶

This resource is used for managing teams and their users in Tower.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
organization	Resource organization	The organization field.	False	False	True	True
description	String	The description field.	False	False	True	False

API Specification¶

class tower_cli.resources.team.Resource: A resource for teams.

associate(**kwargs): Associate a user with this team.

Parameters

team (str) – Primary key or name of the team to associate to.
user (str) – Primary key or name of the user to be associated.

Returns: Dictionary of only one key “changed”, which indicates whether the associate succeeded.
Return type: dict

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(**kwargs): Create an object.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

disassociate(**kwargs): Disassociate a user with this team.

Parameters

team (str) – Primary key or name of the team to disassociate to.
user (str) – Primary key or name of the user to be disassociated.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociate succeeded.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

User¶

Description¶

This resource is used for managing users in Tower.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
username	String	The username field.	False	True	True	True
password	String	The password field.	False	False	True	False
email	String	The email field.	False	True	True	True
first_name	String	The first_name field.	False	False	True	False
last_name	String	The last_name field.	False	False	True	False
is_superuser	bool	The is_superuser field.	False	False	True	False
is_system_auditor	bool	The is_system_auditor field.	False	False	True	False

API Specification¶

class tower_cli.resources.user.Resource: A resource for users.

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(**kwargs): Create an object.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

Workflow Job¶

Description¶

This resource is used for managing workflow jobs and launching workflow job templates via Tower.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
workflow_job_template	Resource workflow	The workflow_job_template field.	False	False	True	True
extra_vars	variables	The extra_vars field.	False	False	True	False
created	String	The created field.	False	False	True	False
status	String	The status field.	False	False	True	False

API Specification¶

class tower_cli.resources.workflow_job.Resource(*args, **kwargs): A resource for workflow jobs.

cancel(pk=None, fail_if_not_running=False, **kwargs): Cancel a currently running job.

Parameters

pk (int) – Primary key of the job resource to restart.
fail_if_not_running (bool) – Flag that if set, raise exception if the job resource cannot be canceled.
**kwargs – Keyword arguments used to look up job resource object to restart if pk is not provided.

Returns: A dictionary of two keys: “status”, which is “canceled”, and “changed”, which indicates if the job resource has been successfully canceled.
Return type: dict
Raises: tower_cli.exceptions.TowerCLIError – When the job resource cannot be canceled and fail_if_not_running flag is on.

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

launch(workflow_job_template=None, monitor=False, wait=False, timeout=None, extra_vars=None, **kwargs): Launch a new workflow job based on a workflow job template.

Parameters

workflow_job_template (str) – Primary key or name of the workflow job template to launch new job.
monitor (bool) – Flag that if set, immediately calls monitor on the newly launched workflow job rather than exiting with a success.
wait (bool) – Flag that if set, monitor the status of the workflow job, but do not print while job is in progress.
timeout (int) – If provided with monitor flag set, this attempt will time out after the given number of seconds.
extra_vars (array of strings) – yaml formatted texts that contains extra variables to pass on.
**kwargs – Fields needed to create and launch a workflow job.

Returns: Result of subsequent monitor call if monitor flag is on; Result of subsequent wait call if wait flag is on; loaded JSON output of the job launch if none of the two flags are on.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

monitor(pk, parent_pk=None, timeout=None, interval=0.5, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='ANSI_X3.4-1968'>, **kwargs): Stream the standard output from a job run to stdout.

Parameters

pk (int) – Primary key of the job resource object to be monitored.
parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be monitored if pk is not set.
timeout (float) – Number in seconds after which this method will time out.
interval (float) – Polling interval to refresh content from Tower.
outfile (file) – Alternative file than stdout to write job stdout to.
**kwargs – Keyword arguments used to look up job resource object to monitor if pk is not provided.

Returns: A dictionary combining the JSON output of the finished job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is finished as expected; “id”, an integer which is the primary key of the job resource object being monitored.
Return type: dict
Raises

tower_cli.exceptions.Timeout – When monitor time reaches time out.
tower_cli.exceptions.JobFailure – When the job being monitored runs into failure.

relaunch(pk=None, **kwargs): Relaunch a stopped job resource.

Parameters

pk (int) – Primary key of the job resource to relaunch.
**kwargs – Keyword arguments used to look up job resource object to relaunch if pk is not provided.

Returns: A dictionary combining the JSON output of the relaunched job resource object, as well as an extra field “changed”, a flag indicating if the job resource object is status-changed as expected.
Return type: dict

status(pk=None, detail=False, **kwargs): Retrieve the current job status.

Parameters

pk (int) – Primary key of the resource to retrieve status from.
detail (bool) – Flag that if set, return the full JSON of the job resource rather than a status summary.
**kwargs – Keyword arguments used to look up resource object to retrieve status from if pk is not provided.

Returns: full loaded JSON of the specified unified job if detail flag is on; trimed JSON containing only “elapsed”, “failed” and “status” fields of the unified job if detail flag is off.
Return type: dict

wait(pk, parent_pk=None, min_interval=1, max_interval=30, timeout=None, outfile=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='ANSI_X3.4-1968'>, exit_on=['successful'], **kwargs): Wait for a job resource object to enter certain status.

Parameters

pk (int) – Primary key of the job resource object to wait.
parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be waited if pk is not set.
timeout (float) – Number in seconds after which this method will time out.
min_interval (float) – Minimum polling interval to request an update from Tower.
max_interval (float) – Maximum polling interval to request an update from Tower.
outfile (file) – Alternative file than stdout to write job status updates on.
exit_on (array) – Job resource object statuses to wait on.
**kwargs – Keyword arguments used to look up job resource object to wait if pk is not provided.

Returns: A dictionary combining the JSON output of the status-changed job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is status-changed as expected; “id”, an integer which is the primary key of the job resource object being status-changed.
Return type: dict
Raises

tower_cli.exceptions.Timeout – When wait time reaches time out.
tower_cli.exceptions.JobFailure – When the job being waited on runs into failure.

Workflow Job Template¶

Description¶

This resource is used for managing workflow job template resources in Tower. It is also responsible for associating/disassociating labels and notification templates to/from an existing job template. There is yet another 2 custom commands, survey, used for getting survey specification of a workflow job template, and schema, used for build workflow topology via YAML/JSON content.

Workflow Schema¶

Workflow schema is a handy API to bulk-create or bulk-update a workflow node network. The schema is a JSON- or YAML-formatted string defining the hierarchy structure that connects the nodes. Names, as well as other valid parameters for node creation, are acceptable inside of the node’s entry inside the schema definition.

Links must be declared as a list under a key that starts with “success”, “failure”, or “always”. The following is an example of a valid YAML-formatted schema definition.

"""
- job_template: Hello world
  failure:
  - inventory_source: AWS servers (AWS servers - 42)
  success:
  - project: Ansible Examples
    always:
    - job_template: Echo variable
      success:
      - job_template: Scan localhost
"""

The workflow schema feature populates the workflow node network based on the hierarchy structure. Before creating each node, it attempts to find an existing node with the specified properties in that location in the tree, and will not create a new node if it exists. Also, if an existing node has no correspondence in the schema, the entire sub-tree based on that node will be deleted.

Thus, after running the schema command, the resulting workflow node network topology will always be exactly the same as what is specified in the given schema file. To continue with the previous example, subsequent invocations of:

wfjt.schema('workflow1', '<schema spec>')

should not change the network of workflow1, since schema detail is unchanged. However

wfjt.schema('workflow1', '<new schema spec>')

will modify node network topology of workflow1 to exactly the same as what is specified in the new schema spec.

Fields Table¶

name	type	help_text	read_only	unique	filterable	required
name	String	The name field.	False	True	True	True
description	String	The description field.	False	False	True	False
extra_vars	variables	Extra variables used by Ansible in YAML or key=value format. Use @ to get YAML from a file. Use the option multiple times to add multiple extra variables.	False	False	True	False
organization	Resource organization	The organization field.	False	False	True	False
survey_enabled	bool	Prompt user for job type on launch.	False	False	True	False
allow_simultaneous	bool	The allow_simultaneous field.	False	False	True	False
survey_spec	variables	On write commands, perform extra POST to the survey_spec endpoint.	False	False	True	False

API Specification¶

class tower_cli.resources.workflow.Resource: A resource for workflow job templates.

associate_label(**kwargs): Associate a label with this workflow_job_template.

Parameters

workflow_job_template (str) – Primary key or name of the workflow_job_template to associate to.
label (str) – Primary key or name of the label to be associated.

Returns: Dictionary of only one key “changed”, which indicates whether the associate succeeded.
Return type: dict

associate_label(**kwargs): Associate a label with this workflow_job_template.

Parameters

workflow_job_template (str) – Primary key or name of the workflow_job_template to associate to.
label (str) – Primary key or name of the label to be associated.

Returns: Dictionary of only one key “changed”, which indicates whether the associate succeeded.
Return type: dict

associate_notification_template(workflow, notification_template, status): Associate a notification template from this workflow job template.

Parameters

workflow (str) – The workflow job template to associate to.
notification_template (str) – The notification template to be associated.
status (str) – type of notification this notification template should be associated to.

Returns: Dictionary of only one key “changed”, which indicates whether the association succeeded.
Return type: dict

copy(pk=None, new_name=None, **kwargs): Copy an object.

Parameters

pk (int) – Primary key of the resource object to be copied
new_name – The new name to give the resource if deep copying via the API
**kwargs – Keyword arguments of fields whose given value will override the original value.

Returns: loaded JSON of the copied new resource object.
Return type: dict

create(**kwargs): Create an object.

Parameters

fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
**kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.

Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: dict

delete(pk=None, fail_on_missing=False, **kwargs): Remove the given object.

Parameters

pk (int) – Primary key of the resource to be deleted.
fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
**kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.

Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type: dict

disassociate_label(**kwargs): Disassociate a label with this workflow_job_template.

Parameters

workflow_job_template (str) – Primary key or name of the workflow_job_template to disassociate to.
label (str) – Primary key or name of the label to be disassociated.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociate succeeded.
Return type: dict

disassociate_notification_template(workflow, notification_template, status): Disassociate a notification template from this workflow job template.

Parameters

job_template (str) – The workflow job template to disassociate from.
notification_template (str) – The notification template to be disassociated.
status (str) – type of notification this notification template should be disassociated from.

Returns: Dictionary of only one key “changed”, which indicates whether the disassociation succeeded.
Return type: dict

get(pk=None, **kwargs): Retrieve one and exactly one object.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.

Returns: loaded JSON of the retrieved resource object.
Return type: dict

list(all_pages=False, **kwargs): Retrieve a list of objects.

Parameters

all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
page (int) – The page to show. Ignored if all_pages is set.
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments list of available fields used for searching resource objects.

Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type: dict

modify(pk=None, create_on_missing=False, **kwargs): Modify an already existing object.

Parameters

pk (int) – Primary key of the resource to be modified.
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
**kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type: dict

schema(wfjt, node_network=None): Convert YAML/JSON content into workflow node objects if node_network param is given. If not, print a YAML representation of the node network.

Parameters

wfjt (str) – Primary key or name of the workflow job template to run schema against.
node_network (str) – JSON- or YAML-formatted string representing the topology of the workflow job template be updated to.

Returns: The latest topology (possibly after modification) of the workflow job template.
Return type: dict

survey(pk=None, **kwargs): Get the survey specification of a resource object.

Parameters

pk (int) – Primary key of the resource to retrieve survey from. Tower CLI will only attempt to read that object if pk is provided (not None).
**kwargs – Keyword arguments used to look up resource object to retrieve survey if pk is not provided.

Returns: loaded JSON of the retrieved survey specification of the resource object.
Return type: dict

Contributor’s Guide¶

All kinds of contributions are more than welcomed. You can help make tower CLI better by reporting bugs, come up with feature ideas or, even further, help maintainers out by making pull requests. Make sure you follow the rules below when contributing and you are ready to roll ;)

Bug Reports¶

Reporting bugs is highly valuable to us. For flexibility, we do not provide issue templates, but describe the issue as specific as possible to make it easier and faster for us to hunt down the issue.

First check existing issues to see if it has already been created, if it has, giving issue description a “thumbs up”.
Mark the issue with ‘bug’ label.
Be sure to mention Tower backend version, Tower CLI version and python interpreter version when the bug occurs.
Copy-paste the detailed usage (code snippet when using as python library and command when using as CLI) and error message if possible.

Feature Requests¶

We welcome all sorts of feature ideas, but note, it may be scheduled for a future release rather than the next one, please be patient while we process your request. We will ping you on github once the feature is implemented.

•: Mark the issue with ‘enhancement’ label.

Architecture Overview¶

All available Tower CLI resources descent from abstract class tower_cli.models.base.BaseResource, which provides two fundamental methods, read and write. read wraps around a GET method to the specified resource, while write wraps around a POST or PATCH on condition. Most public resource APIs, like create or list, are essentially using a combination of read and write to communicate with Tower REST APIs.

class tower_cli.models.base.BaseResource: Abstract class representing resources within the Ansible Tower system, on which actions can be taken. Includes standard create, modify, list, get, and delete methods.
Some of these methods are not created as commands, but will be implemented as commands inside of non-abstract child classes. Particularly, create is not a command in this class, but will be for some (but not all) child classes.

read(pk=None, fail_on_no_results=False, fail_on_multiple_results=False, **kwargs): Retrieve and return objects from the Ansible Tower API.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
fail_on_no_results (bool) – Flag that if set, zero results is considered a failure case and raises an exception; otherwise, empty list is returned. (Note: This is always True if a primary key is included.)
fail_on_multiple_results (bool) – Flag that if set, at most one result is expected, and more results constitutes a failure case. (Note: This is meaningless if a primary key is included, as there can never be multiple results.)
query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
**kwargs – Keyword arguments which, all together, will be used as query parameters to filter resulting resource objects.

Returns: loaded JSON from Tower backend response body.
Return type: dict
Raises

tower_cli.exceptions.BadRequest – When 2-tuples in query overlaps key-value pairs in **kwargs.
tower_cli.exceptions.NotFound – When no objects are found and fail_on_no_results flag is on.
tower_cli.exceptions.MultipleResults – When multiple objects are found and fail_on_multiple_results flag is on.

write(pk=None, create_on_missing=False, fail_on_found=False, force_on_exists=True, **kwargs): Modify the given object using the Ansible Tower API.

Parameters

pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
create_on_missing (bool) – Flag that if set, a new object is created if pk is not set and objects matching the appropriate unique criteria is not found.
fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
force_on_exists (bool) – Flag that if set, then if an object is modified based on matching via unique fields (as opposed to the primary key), other fields are updated based on data sent; If unset, then the non-unique values are only written in a creation case.
**kwargs – Keyword arguments which, all together, will be used as POST/PATCH body to create/modify the resource object. if pk is not set, key-value pairs of **kwargs which are also in resource’s identity will be used to lookup existing reosource.

Returns: A dictionary combining the JSON output of the resource, as well as two extra fields: “changed”, a flag indicating if the resource is created or successfully updated; “id”, an integer which is the primary key of the specified object.
Return type: dict
Raises: tower_cli.exceptions.BadRequest – When required fields are missing in **kwargs when creating a new resource object.

Here is the detailed class hierarchy from tower_cli.models.base.BaseResource to all specific Tower resources:

Details of each Tower CLI resource module are available under tower_cli/resources/.

Some root-level modules under tower_cli/ folder are of great importance. Specifically, api.py contains details of the API client Tower CLI used to make HTTP(S) requests using requests, and conf.py is used to define and initialize singleton setting object tower_cli.conf.settings.

On the other hand, tower_cli/cli/ folder contains code that extends tower_cli from a python library into a full- fledged command-line interface. We use click as the CLI engine.

Code Contributions¶

Setting up development environment and playing around with Tower CLI is quite straight-forward, here is the usual development procedure:

1.: Branch out a local issue branch from the correct base branch.
2.: Create an empty virtual environment.
3.: Code.
4.: Run make install to install development Tower CLI and all its dependency to virtual environment.
5.: Manually test on your bug fix/feature and modify until manual tests pass.
6.: Run sudo pip install tox. Then at the root directory of Tower CLI repository, run sudo tox . to run flake8 verify and unit test against all supported python versions. Run and modify until all flake8 checks and unit tests pass.
7.: Commit, push to local fork and make pull request targeting the correct base branch.
8.: Wait for a maintainer to either approve and merge the pull request, or update pull request according to feedback comment.

Some points to keep in mind when developing:

Target the correct branch. Currently we use branch ‘v1’ to track 3.1.x versions and ‘master’ to track 3.2.0 and beyond.
Consider all API versions. Currently 3.1.x versions are exclusively used for API v1 and 3.2.0 and beyond are exclusively used for API v2, that means if you fixed a bug for 3.1.8, switch to 3.2.0 and see if the same or similar bug exists and needs similar fix.
Consider python 2/3 compatibility, make good use of six and tower_cli.compat.
Consider docs update. Whenever a new resource, new resource public method or new resource field is added, inspect the docs folder and make all necessary updates before committing. Whenever HISTORY.rst at base directory changes replace docs/source/HISTORY.rst with the latest version.
Adhere to the flake8 specifications when developing, the only exception we allow is the maximum line length, which is 120 characters rather than 79.
Be pythonic by using meaningful names and clear structures. Make code self-explanatory rather than adding excessive comments.
Be test-driven. Although not mandatory, please try keeping test coverage at least the same as before, we appreciate it if you can increase our test coverage in your pull requests.

Release History¶

3.3.0 (2018-04-25)¶

Added send and receive commands to export and import resources
Added support for import and export role memberships as well
Added login command for token-based auth (AWX feature)
Added options for workflow nodes and schedules (AWX feature)
Added support for server-side copying (AWX feature)
Added resource for activity stream
Added abstract resource for job events
Bug fixes for label creation, workflow monitor, global config, role list

3.2.1 (2017-12-19)¶

Added support for using settings from environment vars in normal CLI use
Made many-to-many relations easier to manage with a new field type
Installed new CLI entry point, awx-cli
Allowed setup and testing to proceed without root privileges
Added project and inventory update resources to enable more functionality
Fixed bug when copying resources that use the variables field type
Fixed bug that caused debug messages to hang with long line lengths
Fixed bug with side-by-side install of v1 and v2
Fixed bug where –all-pages was ignored for roles
Allowed use of –format=id with multiple results
Added cleaner handling of Unicode

3.2.0 (2017-10-04)¶

General:

Officially support using tower_cli as a python library.
Major documentation updates. From 3.2.0 docs are hosted on http://tower-cli.readthedocs.io.
Added project_update and inventory_update resources to allow canceling and deleting.

Updates from Tower 3.2:

Migrated to API V2. All API calls will start with /api/v2 instead of /api/v1.
Made inventory_source an external resource and remove the old relationship to its associated group. Remove launching inventory updates from group resource.
Added credential_type resource and significantly modified credential resource to reveal user-defined credentials feature of Tower 3.2.
Added job template extra credential (dis)association to reveal extra_credential field of 3.2 job templates.
Removed all source-specific inventory source fields and replaced them with a credential field.
Updated inventory resource fields to reveal smart inventory and insights integration features of Tower 3.2.
Added list_fact and insights commands to host resource to reveal smart inventory and insights integration features of Tower 3.2.
Added instance and instance_group resources to reveal instance/instance group feature of Tower 3.2.
Enabled (dis)associating instance groups to(from) organization, job_template and inventory resources to reveal instance/instance group feature of Tower 3.2.
Added support for Tower 3.2 SCM inventory sources.
Updated job_template resource fields to reveal changes in Tower 3.2, including –diff mode feature.
Updated job resource launch command to reveal changes in Tower 3.2, including –diff mode feature.
Updated ad_hoc resource fields to reveal changes in Tower 3.2, including –diff mode feature. Specifically, changed name of –become of launch command into –become-enabled.

Deprecated features:

Removed permission resource.
Disabled launching a job using the jobs endpoint.
Removed scan jobs in favor of new job fact cache.
Removed Rackspace options.
Remove outdated association function for project’s organization.

Reflected from 3.1.8:

Include method of installing with alias tower-cli-v2
Fix bug of incomplete role membership lookup, preventing granting of roles.
Combine click parameters from multiple base classes in metaclass.
Fix unicode bug in human display format.
Add new page_size parameter to list view.
Add scm_update_cache_timeout field to project resource.
Begin process to deprecate python 2.6.

3.1.7 (2017-08-07)¶

•: Follow up 3.1.6 by duplicating exceptions.py to support import tower_cli.utils.exceptions syntax.

3.1.6 (2017-07-18)¶

•: Fix a usage compatibility issue for Ansible Tower modules.

3.1.5 (2017-07-12)¶

Major code base file structure refactor. Now all click-related logics are moved to tower_cli/cli/ directory, and exceptions.py as well as compat.py are moved out of utils directory into base directory.
Categorize help text options for resource action commands (like update) to increase readability.
Behavior change of workflow schema command. Now schema will both create new nodes and delete existing nodes when needed to make the resulting workflow topology exactly the same as described in schema file.
Add command job_template callback to enable conducting provisioning callback via Tower CLI.
Add new format option to just echo id.
Expand some resource fields, including hipchat rooms for notification template and allow_simultaneous for job templates.
Lookup related inventory sources with “starts with” logic if its name is not fully qualified.
Fixed a python 3.5 compatibility issue that causes job monitor traceback.
Minor typo and help text updates.

3.1.4 (2017-06-07)¶

Support resource copy subcommand.
Support auth-token-based authentication for Tower CLI requests.
Support managing workflow roles, labels and notifications via Tower CLI.
Several fixes on RPM spec file.
Name change from ‘foreman’ to ‘satellite6’ in credential kind choices.
Fixed a bug where creating job templates with –extra-vars did not work after 3.1.0 upgrade.
Fixed traceback when launching job with –use-job-endpoint.
Enhanced json library usage to prevent traceback when using earlier python 2.6 versions.
Prevent throwing unnecessary warning when reading from global configuration file.

3.1.3 (2017-03-22)¶

•: Fixed a bug where extra_vars were dropped in some commands.

3.1.2 (2017-03-21)¶

•: Fixed a bug where global flags are not added to some commands.

3.1.1 (2017-03-13)¶

Fixed a bug which blocks named resources from using runtime configure settings.
Fixed a bug in 3.1.0 which sometimes causes traceback when pk value is given.

3.1.0 (2017-03-09)¶

Improved job monitoring functionality to enable standard out streaming, which displays real-time job output on command line.
Added workflow, workflow_job and node endpoints to manipulate workflow graph and manage workflow job resources. Reflecting workflows feature of Tower 3.1.
Added settings command to manage Tower settings via Tower CLI. Reflecting Configure Tower in Tower (CTiT) feature of Tower 3.1.
Included timeout option to certain unified job template resources. Reflecting job timeout feature of Tower 3.1.
Added unicode support to extra_vars and variable types.
Several minor bug fixes to improve user experience.

3.0.3 (2017-02-07)¶

Expose custom inventory script resource to the user
Include tests and docs in the release tarball
Added job template skip_tags prompting support
Added job template callback support

3.0.2 (2016-12-08)¶

•: Enable configuring tower-cli via environment variables

3.0.1 (2016-09-22)¶

•: Added custom SSL certificate support

3.0.0 (2016-08-05)¶

Added text indicator for resource change
Allow hosts, inventory, and groups to use variables from the command line and denote a file by starting with “@”
Added resource role for tower3.0 and permission for previous tower versions
Added notification templates
Added labels
Added description display option
Added deprecation warnings
Help text upgrades
Give indication of “changed” apart from color
New credential fields to support openstack-v2, networking and azure
New options for inventory source/group. Add implicit resource inventory script.
credential updates (no longer require user/team)
Added support for system auditors
projects (do not post to organizations/N/projects)
prompt-for JT fields + job launch options (allow blank inventory too)
Update the POST protocol for associate and disassociate actions
New job launch option for backwards compatibility
New tower-cli option to display tower-cli version
Enhanced debug log format (support multi-line debug log)

2.3.2 (2016-07-21)¶

Add RPM specfile and Makefile
Tower compatibility fixes
Allow scan JTs as an option for “job_type”
Add ability to create group as subgroup of another group
Add YAML output format against JSON and humanized output formats
Add SSL corner case error handling and suggestion
Allow resource disassociation with “null”

2.3.1 (2015-12-10)¶

Fixed bug affecting force-on-exists and fail_on_found options
Changed extra_vars behavior to be more compliant by re-parsing vars, even when only one source exists
Fixed group modify bug, avoid sending unwanted fields in modify requests

2.3.0 (2015-10-20)¶

Fixed an issue where the settings file could be world readable
Added the ability to associate a project with an organization
Added setting “verify_ssl” to disallow insecure connections
Added support for additional cloud credentials
Exposed additional options for a cloud inventory source
Combined ” launch-time extra_vars” with ” job_template extra_vars” for older Tower versions
Changed the extra_vars parameters to align with Ansible parameter handling
Added the ability to run ad hoc commands
Included more detail when displaying job information
Added an example bash script to demonstrate tower-cli usage

2.1.1 (2015-01-27)¶

Added tests for Python versions 2.6 through 3.4
Added shields for github README
Added job_tags on job launches
Added option for project local path

2.1.0 (2015-01-21)¶

Added the ability to customize the set of fields used as options for a resource
Expanded monitoring capability to include projects and inventory sources
Added support for new job_template job launch endpoint

2.0.2 (2014-10-02)¶

Added ability to set local scope for config file
Expanded credential resource to allow options for cloud credentials

2.0.1 (2014-07-18)¶

•: Updated README and error text

2.0.0 (2014-07-15)¶

•: Pluggable resource architecture built around click

Source file:	tower-cli.1.en.gz (from ansible-tower-cli 3.3.0-1)
Source last updated:	2018-08-19T08:54:54Z
Converted to HTML:	2020-08-08T10:02:53Z

NAME¶

ABOUT TOWER¶

CAPABILITIES¶

TABLE OF CONTENTS¶

Installation¶

Install from Package Managers¶

Build from Source¶

Quick Start¶

CLI Reference¶

Config Command Options¶

key-value options available for tower-cli config <key> <value> command¶

Environment Variables¶

Variable Mapping¶

Notes¶

Versioning of tower-cli¶

API Versions¶

Supported Versions with Ansible Tower¶

Policy with AWX Versions¶

API Version Upgrade Guide¶

API v1->v2¶

Version-specific Secondary Install¶

Notification Template Management¶

Introduction - What Notification Templates Are¶

Managing Notification Templates with tower-cli¶

Basic Operations¶

Detailed Example¶

Role Management¶

Introduction - What Roles Are¶

Managing Roles with tower-cli¶

Basic Operations¶

Detailed Example¶

Organization and Team Roles¶

Survey Management¶

View a Survey¶

Save a survey¶

Copy a survey to another template¶

Workflows¶

Workflow Management¶

Normal CRUD¶

Workflow Creation¶

Node Creation¶

Node Association¶

Node Network Bulk Management¶

Creating/updating a Schema Definition¶

Differences with Machine Formatted Schemas¶

Idempotence¶

Launching Workflow Jobs¶

Example Commands¶

Setup¶

Create Fake Data¶

Cleaning Up¶

Warnings¶

Python Module Use Example¶

API Reference¶

Introduction¶

Configuration¶

Exceptions¶

API Reference Table of Contents¶

Ad Hoc Commands¶

Description¶

Fields Table¶

API Specification¶

Credential Type¶

Description¶

Fields Table¶

API Specification¶

Credential¶

Description¶

Fields Table¶

API Specification¶

Group¶

Description¶

Fields Table¶

API Specification¶

Host¶

Description¶

Fields Table¶

API Specification¶

Instance Group¶

Description¶