The AWX CLI supports multiple configuration methods including command-line flags, environment variables, and configuration files. This guide covers all available configuration options.
Authentication
The AWX CLI requires authentication to interact with AWX or Ansible Automation Platform instances. There are several methods to provide credentials.
Command-Line Authentication
Provide credentials directly with each command:
awx --conf.host https://awx.example.org \
--conf.username alice \
--conf.password secret \
users list
Environment Variables
Set environment variables for persistent authentication:
export CONTROLLER_HOST=https://awx.example.org
export CONTROLLER_USERNAME=alice
export CONTROLLER_PASSWORD=secret
awx users list
For backward compatibility, TOWER_HOST, TOWER_USERNAME, and TOWER_PASSWORD are also supported but deprecated.
Credential Files
The CLI can load credentials from a configuration file. Create a credentials file:
mkdir -p ~/.awx
cat > ~/.awx/credentials.yml <<EOF
default:
username: alice
password: secret
EOF
export AWXKIT_CREDENTIAL_FILE=~/.awx/credentials.yml
export CONTROLLER_HOST=https://awx.example.org
awx users list
Authentication Methods
Session-Based Authentication (Default)
By default, the CLI uses session-based authentication, which is more efficient for multiple commands:
# First command establishes a session
awx jobs list
# Subsequent commands reuse the session
awx projects list
~/.awx/sessions/ and automatically managed.
Basic Authentication
For environments like AAP Gateway where session login is restricted, force Basic authentication:
export AWXKIT_FORCE_BASIC_AUTH=true
export CONTROLLER_USERNAME=alice
export CONTROLLER_PASSWORD=secret
awx users list
Basic authentication requires credentials on every request. Ensure both username and password are provided when AWXKIT_FORCE_BASIC_AUTH is enabled.
Connection Settings
Host Configuration
Specify the AWX/AAP host URL:
# Command-line flag
awx --conf.host https://awx.example.org users list
# Environment variable
export CONTROLLER_HOST=https://awx.example.org
awx users list
https://127.0.0.1:443
SSL Certificate Verification
By default, SSL certificates are verified. For self-signed certificates or testing:
# Command-line flag
awx --conf.insecure users list
awx -k users list # Short form
# Environment variable
export CONTROLLER_VERIFY_SSL=false
awx users list
Disabling SSL verification exposes you to man-in-the-middle attacks. Only use this in trusted development environments.
API Base Path
For Red Hat Ansible Automation Platform 2.5+, set the API base path:
export AWXKIT_API_BASE_PATH=/api/controller/
export AWXKIT_API_BASE_PATH=/api/
/api/
The CLI supports multiple output formats:
JSON (default)
YAML
Human-readable table
JQ filtering (requires jq extra)
Filter Output
Use the --filter flag to select specific fields:
# Human format with custom columns
awx users list -f human --filter 'id,username,email'
# JQ format with complex queries
awx users list -f jq --filter '.results[] | {id, username}'
Color Output
Control colored output:
# Enable color (default)
awx --conf.color true users list
# Disable color
awx --conf.color false users list
# Environment variable
export CONTROLLER_COLOR=false
Verbose Output
Enable debug logging to see HTTP requests:
awx -v users list
awx --verbose users list
# Environment variable
export CONTROLLER_VERBOSE=true
Configuration Priority
When multiple configuration sources are present, they are evaluated in this order (highest to lowest priority):
- Command-line flags (
--conf.*)
- Environment variables (
CONTROLLER_*)
- Credential files (
AWXKIT_CREDENTIAL_FILE)
- Default values
Complete Configuration Example
Create a comprehensive shell configuration:
# ~/.awxrc
export CONTROLLER_HOST=https://awx.example.org
export CONTROLLER_USERNAME=alice
export CONTROLLER_PASSWORD=secret
export CONTROLLER_VERIFY_SSL=true
export CONTROLLER_FORMAT=human
export CONTROLLER_COLOR=true
export AWXKIT_API_BASE_PATH=/api/
echo 'source ~/.awxrc' >> ~/.bashrc
Verify Configuration
To verify your current configuration:
This displays:
- Base URL
- Session authentication status
- Current credentials (username only, not password)
Environment Variable Reference
| Variable | Description | Default |
|---|
CONTROLLER_HOST | AWX/AAP host URL | https://127.0.0.1:443 |
CONTROLLER_USERNAME | Authentication username | admin |
CONTROLLER_PASSWORD | Authentication password | password |
CONTROLLER_VERIFY_SSL | Enable SSL verification | true |
CONTROLLER_FORMAT | Output format (json/yaml/human/jq) | json |
CONTROLLER_COLOR | Enable colored output | true |
CONTROLLER_VERBOSE | Enable debug logging | false |
AWXKIT_API_BASE_PATH | API base path | /api/ |
AWXKIT_CREDENTIAL_FILE | Path to credentials file | None |
AWXKIT_FORCE_BASIC_AUTH | Force Basic authentication | false |
Command-Line Flag Reference
| Flag | Environment Variable | Description |
|---|
--conf.host | CONTROLLER_HOST | AWX/AAP host URL |
--conf.username | CONTROLLER_USERNAME | Username for authentication |
--conf.password | CONTROLLER_PASSWORD | Password for authentication |
-k, --conf.insecure | CONTROLLER_VERIFY_SSL | Allow insecure SSL connections |
-f, --conf.format | CONTROLLER_FORMAT | Output format |
--filter | - | Output field filter |
--conf.color | CONTROLLER_COLOR | Enable/disable colors |
-v, --verbose | CONTROLLER_VERBOSE | Enable verbose logging |
--version | - | Show CLI version |
--help | - | Show help message |
Troubleshooting
Connection Errors
Error: Connection refused
# Check host URL is correct
echo $CONTROLLER_HOST
# Verify AWX is accessible
curl -k $CONTROLLER_HOST/api/v2/
# For self-signed certificates, use -k flag
awx -k users list
# Or disable verification
export CONTROLLER_VERIFY_SSL=false
Authentication Errors
Error: Unauthorized (401)
# Verify credentials
awx config
# Try explicit credentials
awx --conf.username admin --conf.password password users list
# Enable Basic auth for AAP Gateway
export AWXKIT_FORCE_BASIC_AUTH=true
AAP 2.5+ Path Issues
Error: Unable to fetch /api/v2/
# Set correct API base path
export AWXKIT_API_BASE_PATH=/api/controller/
Security Best Practices
- Never commit credentials to version control
- Use environment variables instead of command-line flags in scripts (flags may appear in process lists)
- Restrict credential file permissions:
chmod 600 ~/.awx/credentials.yml
- Use separate credentials for automation vs. interactive use
- Enable SSL verification in production environments
- Rotate passwords regularly
- Use RBAC to limit CLI user permissions to only what’s needed
