> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ansible/awx/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Commands Reference

> Complete reference of AWX CLI resources, actions, and arguments

This reference documents all available AWX CLI resources, their actions, and common arguments. The exact list of resources and actions may vary based on your AWX version and permissions.

## Command Discovery

The AWX CLI is self-documenting. Resources and actions are discovered dynamically from the AWX API using HTTP OPTIONS requests.

### List All Resources

```bash theme={null}
awx --conf.host https://awx.example.org --help
```

### Get Resource Details

```bash theme={null}
awx <resource> --help
```

### Get Action Details

```bash theme={null}
awx <resource> <action> --help
```

## Standard Actions

Most resources support these standard CRUD actions:

### list

List all resources of the specified type.

```bash theme={null}
awx <resource> list [options]
```

**Common Options:**

* `--all` - Fetch all pages (default: first page only)
* `--order_by FIELD` - Sort by field (prefix with `-` for descending)
* `-f, --conf.format` - Output format (json, yaml, human, jq)
* `--filter` - Field filter for output

**Examples:**

```bash theme={null}
awx users list
awx users list --all
awx users list --order_by username
awx users list -f human --filter 'id,username,email'
```

### get

Retrieve a specific resource by ID or name.

```bash theme={null}
awx <resource> get <id|name> [options]
```

**Arguments:**

* `id` - Resource ID (integer) or unique name (string)

**Examples:**

```bash theme={null}
awx users get 1
awx users get alice
awx projects get 'My Project'
```

### create

Create a new resource.

```bash theme={null}
awx <resource> create [required-args] [optional-args]
```

**Common Patterns:**

* Required fields are shown in "required arguments" section
* Use `--help` to see all available fields
* JSON/YAML fields accept `@filename` for file input

**Examples:**

```bash theme={null}
awx users create --username bob --password secret --email bob@example.com
awx projects create --name 'My Project' --organization 1 --scm_type git --scm_url 'https://github.com/example/repo.git'
```

### modify

Update an existing resource.

```bash theme={null}
awx <resource> modify <id|name> [fields-to-update]
```

**Examples:**

```bash theme={null}
awx users modify alice --email alice@newdomain.com
awx projects modify 'My Project' --scm_branch main
```

### delete

Delete a resource.

```bash theme={null}
awx <resource> delete <id|name>
```

**Examples:**

```bash theme={null}
awx users delete bob
awx projects delete 42
```

## Common Resources

### users

Manage AWX users.

**Actions:** list, get, create, modify, delete, grant, revoke

**Create Example:**

```bash theme={null}
awx users create \
    --username alice \
    --password secret123 \
    --email alice@example.com \
    --first_name Alice \
    --last_name Smith \
    --is_superuser false
```

**Grant Role:**

```bash theme={null}
awx users grant alice --organization 1 --role admin
awx users grant alice --project 'My Project' --role use
```

### organizations

Manage organizations.

**Actions:** list, get, create, modify, delete, associate, disassociate

**Create Example:**

```bash theme={null}
awx organizations create \
    --name 'Engineering' \
    --description 'Engineering team resources'
```

**Associate Galaxy Credential:**

```bash theme={null}
awx organizations associate 'Engineering' --galaxy_credential 'Ansible Galaxy'
```

### projects

Manage projects (SCM repositories).

**Actions:** list, get, create, modify, delete, update, associate, disassociate

**Create Example:**

```bash theme={null}
awx projects create \
    --name 'Web Application' \
    --organization 'Engineering' \
    --scm_type git \
    --scm_url 'https://github.com/example/webapp.git' \
    --scm_branch main \
    --scm_update_on_launch true
```

**Update Project (SCM sync):**

```bash theme={null}
awx projects update 'Web Application'
awx projects update 'Web Application' --monitor
```

### inventories

Manage inventories.

**Actions:** list, get, create, modify, delete

**Create Example:**

```bash theme={null}
awx inventories create \
    --name 'Production' \
    --organization 'Engineering' \
    --description 'Production servers'
```

### hosts

Manage inventory hosts.

**Actions:** list, get, create, modify, delete

**Create Example:**

```bash theme={null}
awx hosts create \
    --name 'web1.example.com' \
    --inventory 'Production' \
    --variables '{"ansible_host": "10.0.1.10"}'
```

### groups

Manage inventory groups.

**Actions:** list, get, create, modify, delete

**Create Example:**

```bash theme={null}
awx groups create \
    --name 'webservers' \
    --inventory 'Production' \
    --variables '{"http_port": 8080}'
```

### inventory\_sources

Manage dynamic inventory sources.

**Actions:** list, get, create, modify, delete, update

**Create Example:**

```bash theme={null}
awx inventory_sources create \
    --name 'AWS EC2' \
    --inventory 'Production' \
    --source 'ec2' \
    --credential 'AWS Credential' \
    --update_on_launch true
```

**Update Inventory:**

```bash theme={null}
awx inventory_sources update 'AWS EC2' --monitor
```

### credentials

Manage credentials.

**Actions:** list, get, create, modify, delete

**Machine Credential Example:**

```bash theme={null}
awx credentials create \
    --name 'SSH Key' \
    --credential_type 'Machine' \
    --organization 'Engineering' \
    --inputs '{"username": "ansible", "ssh_key_data": "@~/.ssh/id_rsa"}'
```

**Source Control Credential Example:**

```bash theme={null}
awx credentials create \
    --name 'GitHub Token' \
    --credential_type 'Source Control' \
    --organization 'Engineering' \
    --inputs '{"username": "oauth2", "password": "ghp_xxxxxxxxxxxx"}'
```

### credential\_types

Manage custom credential types.

**Actions:** list, get, create, modify, delete

**Example:**

```bash theme={null}
awx credential_types create \
    --name 'API Token' \
    --kind 'cloud' \
    --inputs '{"fields": [{"id": "api_token", "label": "API Token", "type": "string", "secret": true}]}' \
    --injectors '{"env": {"API_TOKEN": "{{ api_token }}"}}'
```

### job\_templates

Manage job templates.

**Actions:** list, get, create, modify, delete, launch, associate, disassociate

**Create Example:**

```bash theme={null}
awx job_templates create \
    --name 'Deploy Application' \
    --job_type run \
    --inventory 'Production' \
    --project 'Web Application' \
    --playbook 'deploy.yml' \
    --verbosity 0
```

**Launch:**

```bash theme={null}
awx job_templates launch 'Deploy Application'
awx job_templates launch 'Deploy Application' --monitor
awx job_templates launch 'Deploy Application' --extra_vars '{"version": "1.2.3"}'
```

**Associate Credential:**

```bash theme={null}
awx job_templates associate 'Deploy Application' --credential 'SSH Key'
```

### workflow\_job\_templates

Manage workflow job templates.

**Actions:** list, get, create, modify, delete, launch, associate, disassociate

**Create Example:**

```bash theme={null}
awx workflow_job_templates create \
    --name 'Deploy Pipeline' \
    --organization 'Engineering' \
    --inventory 'Production'
```

**Launch:**

```bash theme={null}
awx workflow_job_templates launch 'Deploy Pipeline' --monitor
```

### jobs

View and manage job executions.

**Actions:** list, get, delete, stdout, monitor

**List Recent Jobs:**

```bash theme={null}
awx jobs list --all --order_by '-created' -f human
```

**Get Job Output:**

```bash theme={null}
awx jobs stdout 123
```

**Monitor Running Job:**

```bash theme={null}
awx jobs monitor 123
```

**Cancel Job:**

```bash theme={null}
awx jobs delete 123
```

### workflow\_jobs

View and manage workflow job executions.

**Actions:** list, get, delete, monitor

**Monitor Workflow:**

```bash theme={null}
awx workflow_jobs monitor 456
```

### ad\_hoc\_commands

Execute ad hoc commands.

**Actions:** list, get, create, stdout

**Run Ad Hoc Command:**

```bash theme={null}
awx ad_hoc_commands create \
    --inventory 'Production' \
    --credential 'SSH Key' \
    --module_name ping \
    --limit 'webservers'

awx ad_hoc_commands create \
    --inventory 'Production' \
    --credential 'SSH Key' \
    --module_name command \
    --module_args 'uptime' \
    --limit 'all' \
    --monitor
```

### teams

Manage teams.

**Actions:** list, get, create, modify, delete, grant, revoke

**Create Example:**

```bash theme={null}
awx teams create \
    --name 'DevOps' \
    --organization 'Engineering' \
    --description 'DevOps team'
```

**Grant Role:**

```bash theme={null}
awx teams grant 'DevOps' --project 'Web Application' --role admin
```

### schedules

Manage scheduled jobs.

**Actions:** list, get, create, modify, delete

**Create Example:**

```bash theme={null}
awx schedules create \
    --name 'Nightly Backup' \
    --unified_job_template 42 \
    --rrule 'DTSTART:20260301T020000Z RRULE:FREQ=DAILY;INTERVAL=1' \
    --enabled true
```

### notification\_templates

Manage notification templates.

**Actions:** list, get, create, modify, delete

**Email Notification Example:**

```bash theme={null}
awx notification_templates create \
    --name 'Email Alerts' \
    --notification_type email \
    --organization 'Engineering' \
    --notification_configuration '{"host": "smtp.example.com", "recipients": ["alerts@example.com"], "sender": "awx@example.com"}'
```

**Slack Notification Example:**

```bash theme={null}
awx notification_templates create \
    --name 'Slack Alerts' \
    --notification_type slack \
    --organization 'Engineering' \
    --notification_configuration '{"token": "xoxb-xxxx", "channels": ["#alerts"]}'
```

### instances

View AWX instances (Tower/Controller nodes).

**Actions:** list, get

**List Instances:**

```bash theme={null}
awx instances list -f human --filter 'id,hostname,capacity,version'
```

### instance\_groups

Manage instance groups.

**Actions:** list, get, create, modify, delete

**Create Example:**

```bash theme={null}
awx instance_groups create \
    --name 'High Priority' \
    --policy_instance_percentage 100
```

### execution\_environments

Manage execution environments.

**Actions:** list, get, create, modify, delete

**Create Example:**

```bash theme={null}
awx execution_environments create \
    --name 'Custom EE' \
    --image 'quay.io/ansible/awx-ee:latest' \
    --organization 'Engineering' \
    --credential 'Container Registry'
```

### labels

Manage labels.

**Actions:** list, get, create, modify, delete

**Create Example:**

```bash theme={null}
awx labels create \
    --name 'production' \
    --organization 'Engineering'
```

### roles

View available roles.

**Actions:** list, get

**List Roles:**

```bash theme={null}
awx roles list -f human
```

### applications

Manage OAuth2 applications.

**Actions:** list, get, create, modify, delete

**Create Example:**

```bash theme={null}
awx applications create \
    --name 'CI/CD Integration' \
    --organization 'Engineering' \
    --authorization_grant_type 'password' \
    --client_type 'confidential'
```

## Special Actions

### launch

Available for: job\_templates, workflow\_job\_templates

Launch a job or workflow.

**Options:**

* `--monitor` - Stream job output
* `--wait` - Wait for completion without output
* `--action-timeout SECONDS` - Timeout for monitoring
* `--interval SECONDS` - Polling interval (min 2.5s)
* `--extra_vars JSON` - Runtime variables
* `--limit HOST_PATTERN` - Limit to hosts
* `--job_tags TAGS` - Run specific tags
* `--skip_tags TAGS` - Skip specific tags

### update

Available for: projects, inventory\_sources

Trigger an SCM update or inventory sync.

**Options:**

* `--monitor` - Show update progress
* `--wait` - Wait for completion

### monitor

Available for: jobs, workflow\_jobs

Monitor a running or completed job.

```bash theme={null}
awx jobs monitor 123
```

### stdout

Available for: jobs, ad\_hoc\_commands, project\_updates, inventory\_updates

Retrieve job output.

```bash theme={null}
awx jobs stdout 123
```

### grant / revoke

Available for: users, teams

Grant or revoke role-based access.

**Options:**

* `--organization ID|NAME`
* `--project ID|NAME`
* `--inventory ID|NAME`
* `--job_template ID|NAME`
* `--workflow_job_template ID|NAME`
* `--credential ID|NAME`
* `--role ROLE_NAME` (required)

**Available Roles:**

* admin
* execute
* read
* use
* update
* adhoc
* member
* auditor

### associate / disassociate

Available for: job\_templates, workflow\_job\_templates, organizations, projects, inventory\_sources

Associate or disassociate related resources.

**Examples:**

```bash theme={null}
# Associate credential
awx job_templates associate 'Deploy' --credential 'SSH Key'

# Associate notification
awx job_templates associate 'Deploy' --success_notification 'Slack'
awx job_templates associate 'Deploy' --failure_notification 'Email'

# Disassociate
awx job_templates disassociate 'Deploy' --credential 'SSH Key'
```

## Bulk Operations

### bulk

Perform bulk operations.

**Actions:** host\_create, host\_delete, job\_launch

**Bulk Host Create:**

```bash theme={null}
awx bulk host_create \
    --inventory 'Production' \
    --hosts '[{"name": "web1"}, {"name": "web2"}, {"name": "web3"}]'
```

**Bulk Host Delete:**

```bash theme={null}
awx bulk host_delete \
    --hosts '[{"name": "web1"}, {"name": "web2"}]'
```

**Bulk Job Launch:**

```bash theme={null}
awx bulk job_launch \
    --jobs '[{"unified_job_template": 1}, {"unified_job_template": 2}]' \
    --monitor
```

## Control Resources

These resources provide metadata and don't follow standard CRUD patterns.

### config

Display current CLI configuration.

```bash theme={null}
awx config
```

### ping

Test API connectivity.

```bash theme={null}
awx ping
```

### me

View current user details.

```bash theme={null}
awx me list
```

### metrics

View system metrics (if enabled).

```bash theme={null}
awx metrics list
awx metrics list -f human
```

### mesh\_visualizer

View mesh topology (AWX with mesh enabled).

```bash theme={null}
awx mesh_visualizer list
```

### settings

View and modify system settings.

**List All Settings:**

```bash theme={null}
awx settings list
```

**List Settings Category:**

```bash theme={null}
awx settings list --slug authentication
awx settings list --slug jobs
awx settings list --slug system
```

**Modify Setting:**

```bash theme={null}
awx settings modify SESSION_COOKIE_AGE 3600
awx settings modify TOWER_URL_BASE 'https://awx.example.org'
```

## Import/Export Commands

### export

Export resources.

**Syntax:**

```bash theme={null}
awx export [--resource [id|name] ...] [-f json|yaml]
```

**Examples:**

```bash theme={null}
# Export everything
awx export > backup.json

# Export specific types
awx export --users --organizations --teams > rbac.json

# Export by name
awx export --users alice --projects 'My Project' > config.json

# Export by ID
awx export --job_templates 42 > template.json

# Export in YAML
awx export -f yaml > backup.yml
```

**Exportable Resources:**

* users
* organizations
* teams
* credentials
* credential\_types
* notification\_templates
* projects
* inventories
* inventory\_sources
* job\_templates
* workflow\_job\_templates
* schedules
* labels

### import

Import resources.

**Syntax:**

```bash theme={null}
awx import [-f json|yaml] < input_file
```

**Examples:**

```bash theme={null}
# Import from JSON
awx import < backup.json

# Import from YAML
awx import -f yaml < backup.yml
```

## Tips for Working with Commands

### Finding Field Names

Use `--help` to discover available fields:

```bash theme={null}
awx users create --help
```

Or use verbose mode to see API schema:

```bash theme={null}
awx -v users list | grep -A 50 OPTIONS
```

### Using IDs vs Names

Most resources accept either ID or unique name:

```bash theme={null}
# By ID (faster, but less readable)
awx projects get 42

# By name (more readable)
awx projects get 'My Project'
```

### Lookup by Name in Related Fields

When creating resources with foreign keys:

```bash theme={null}
# Reference by ID
awx job_templates create --project 42 --inventory 10 ...

# Reference by name (CLI resolves to ID)
awx job_templates create --project 'My Project' --inventory 'Production' ...
```

### Handling Ambiguous Names

If multiple resources have the same name:

```bash theme={null}
# Error: Multiple projects exist with that name
# Resolution: Use ID or query to find correct one
awx projects list --name 'My Project' -f human
awx projects get 42
```

### Working with Extra Vars

Job templates and workflow templates support extra variables:

```bash theme={null}
# Inline JSON
awx job_templates launch 1 --extra_vars '{"version": "1.2.3"}'

# Short form
awx job_templates launch 1 -e '{"version": "1.2.3"}'

# From file
awx job_templates launch 1 --extra_vars @vars.json
awx job_templates launch 1 --extra_vars @vars.yml
```

### Working with Variables

Inventories, groups, and hosts support variables:

```bash theme={null}
# Inline JSON
awx hosts create --inventory 1 --name web1 \
    --variables '{"ansible_host": "10.0.1.10", "http_port": 8080}'

# From file
awx hosts create --inventory 1 --name web1 --variables @host_vars.yml
```

## Deprecated Resource Names

The CLI supports backward-compatible aliases for resources (for tower-cli compatibility):

| Current Name | Deprecated Alias |
| - | - |
| ad\_hoc\_commands | ad\_hoc |
| applications | application |
| credentials | credential |
| credential\_types | credential\_type |
| groups | group |
| hosts | host |
| inventories | inventory (note: plural is current) |
| inventory\_sources | inventory\_source |
| inventory\_updates | inventory\_update |
| jobs | job |
| job\_templates | job\_template |
| execution\_environments | execution\_environment |
| labels | label |
| workflow\_job\_template\_nodes | node |
| notification\_templates | notification\_template |
| organizations | organization |
| projects | project |
| project\_updates | project\_update |
| schedules | schedule |
| settings | setting |
| teams | team |
| workflow\_job\_templates | workflow |
| workflow\_jobs | workflow\_job |
| users | user |

<Warning>
  Deprecated aliases are provided for compatibility only. Use the current resource names in new scripts and documentation.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.