Basic Usage¶

Installation¶

On Red Hat Enterprise Linux 8, the Controller CLI can be installed via dnf:

dnf install --enablerepo=ansible-automation-platform-2.4-for-rhel-8-x86_64-rpms automation-controller-cli

On Red Hat Enterprise Linux 9, the Controller CLI can be installed via dnf:

dnf install --enablerepo=ansible-automation-platform-2.4-for-rhel-9-x86_64-rpms automation-controller-cli

Note

For AWX deployments, the CLI can be installed via pip. You should first try using the specific version of awxkit that matches your installation by specifying a version. For example:

pip install --upgrade awxkit==21.7.0

To download an installation or for more information about the awx version of the CLI, see https://pypi.org/project/awxkit/.

Synopsis¶

awx commands follow a simple format:

awx [<global-options>] <resource> <action> [<arguments>]
awx --help

The resource is a type of object within AWX (a noun), such as users or organizations.

The action is the thing you want to do (a verb). Resources generally have a base set of actions (get, list, create, modify, and delete), and have options corresponding to fields on the object in AWX. Some resources have special actions, like job_templates launch.

Getting Started¶

Using awx requires some initial configuration. Here is a simple example for interacting with an AWX or Red Hat Ansible Automation Platform controller server:

awx --conf.host https://awx.example.org \
    --conf.username joe --conf.password secret \
    --conf.insecure \
    users list

There are multiple ways to configure and authenticate with an AWX or Red Hat Ansible Automation Platform controller server. For more details, see Authentication.

By default, awx prints valid JSON for successful commands. Certain commands (such as those for printing job stdout) print raw text and do not allow for custom formatting. For details on customizing awx’s output format, see Output Formatting.

Resources and Actions¶

To get a list of available resources:

awx --conf.host https://awx.example.org --help

To get a description of a specific resource, and list its available actions (and their arguments):

awx --conf.host https://awx.example.org users --help
awx --conf.host https://awx.example.org users create --help

Note

The list of resources and actions may vary based on context. For example, certain resources may not be available based on role-based access control (e.g., if you do not have permission to launch certain Job Templates, launch may not show up as an action for certain job_templates objects.

Global Options¶

awx accepts global options that control overall behavior. In addition to CLI flags, most global options have a corresponding environment variable that may be used to set the value. If both are provided, the command line option takes priority.

A few of the most important ones are:

-h, --help: Prints usage information for the awx tool
-v, --verbose: prints debug-level logs, including HTTP(s) requests made
-f, --conf.format: used to specify a custom output format (the default is json)
--conf.host, CONTROLLER_HOST: the full URL of the AWX/Red Hat Ansible Automation Platform controller host (i.e., https://my.awx.example.org)
-k, --conf.insecure, CONTROLLER_VERIFY_SSL: allows insecure server connections when using SSL
--conf.username, CONTROLLER_USERNAME: the AWX username to use for authentication
--conf.password, CONTROLLER_PASSWORD: the AWX password to use for authentication
--conf.token, CONTROLLER_OAUTH_TOKEN: an OAuth2.0 token to use for authentication