Ubuntu Manpage: tower_cli - tower

Provided by: ansible-tower-cli_3.3.0-1.1_all

NAME

       tower_cli - tower_cli Documentation

       tower-cli  is  a  command line tool for Ansible Tower. It allows Tower commands to be easily run from the
       Unix command line. It can also be used as a client library for other python apps, or as a  reference  for
       others developing API interactions with Tower’s REST API.

ABOUT TOWER

       Ansible  Tower  is  a GUI and REST interface for Ansible that supercharges it by adding RBAC, centralized
       logging, autoscaling/provisioning callbacks, graphical inventory editing, and more.

       Tower is free to use for up to 30 days or 10 nodes. Beyond this, a license is required.

CAPABILITIES

       This command line tool sends commands to the Tower API. It is capable of retrieving, creating, modifying,
       and deleting most resources within Tower.

       A few potential uses include:

       • Launching playbook runs (for instance, from Jenkins, TeamCity, Bamboo, etc)

       • Checking on job statuses

       • Rapidly creating objects like organizations, users, teams, and more

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 Output format. The “human”
(‘human’, ‘json’, format is intended for
‘yaml’)/’human’ humans reading output on the
CLI; the “json” and “yaml”
formats provide more data.
───────────────────────────────────────────────────────────────────────────────────
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.
───────────────────────────────────────────────────────────────────────────────────
String/’’ Password to use to
`` authenticate to Ansible
pas sword `` Tower.
───────────────────────────────────────────────────────────────────────────────────
String/’’ Username to use to
`` authenticate to Ansible
use rname `` Tower.
───────────────────────────────────────────────────────────────────────────────────
ver ify_s sl Boolean/’true’ Whether to force verified
SSL connections.
───────────────────────────────────────────────────────────────────────────────────
Boolean/’false’ Whether to show information
`` about requests being made.
ver bose` `
───────────────────────────────────────────────────────────────────────────────────
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.
┌───────────────────┬──────────────────────────────┬──────────────────────────────┐
│ │ │ │
--

AUTHOR

       Alan Rominger, Luke Sneeringer, Aaron Tan

COPYRIGHT

       2019, Ansible by Red Hat

                                                  Oct 19, 2019                                      TOWER_CLI(1)

NAME

ABOUT TOWER

CAPABILITIES

TABLE OF CONTENTS

AUTHOR

COPYRIGHT