mirror of
https://github.com/ansible/tower-cli.git
synced 2026-02-06 18:47:28 +01:00
253 lines
10 KiB
ReStructuredText
253 lines
10 KiB
ReStructuredText
.. _cli_ref:
|
|
|
|
CLI Reference
|
|
=============
|
|
|
|
CLI invocation generally follows this format:
|
|
|
|
.. code:: bash
|
|
|
|
$ 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:
|
|
|
|
.. code:: bash
|
|
|
|
# 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!
|
|
|
|
.. code:: bash
|
|
|
|
$ 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:
|
|
|
|
.. code:: bash
|
|
|
|
$ 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:
|
|
|
|
.. code:: bash
|
|
|
|
$ 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:
|
|
|
|
.. code:: bash
|
|
|
|
$ 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.
|
|
|
|
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 :ref:`api-ref-conf`.
|
|
|
|
.. toctree::
|
|
:maxdepth: 0
|
|
:caption: Usage Guides
|
|
|
|
usage/CONFIG_CMD_OPTIONS.rst
|
|
usage/VERSIONING.rst
|
|
usage/NOTIFICATION_TEMPLATE_MANAGEMENT.rst
|
|
usage/ROLE_MANAGEMENT.rst
|
|
usage/SURVEYS.rst
|
|
usage/WORKFLOWS.rst
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
:caption: Examples
|
|
|
|
examples/README.rst
|
|
|