$ 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
# Set OAuth2 Token for Authentication
$ tower-cli login <username>
# you will be prompted for a password, then an OAuth2 token will be created in AWX/Tower and used for future Authentication.
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.
If set to ASK you will be prompted to
input the password.
-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.