{"id":7923,"library":"ansible-tower-cli","title":"Ansible Tower CLI","description":"Ansible Tower CLI (tower-cli) is a command-line interface tool for interacting with Ansible Tower and AWX instances. It allows users to manage resources like job templates, inventories, and projects directly from the terminal, and also provides a programmatic interface for Python scripts. The library is currently at version 3.3.9 and receives regular updates, typically with several minor releases focusing on bug fixes and new features throughout the year.","status":"active","version":"3.3.9","language":"en","source_language":"en","source_url":"https://github.com/ansible/tower-cli","tags":["ansible","awx","cli","automation","devops","tower"],"install":[{"cmd":"pip install ansible-tower-cli","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for HTTP communication with the Tower/AWX API.","package":"requests"}],"imports":[{"note":"`tower_cli.get_resource` is the official and more direct way to access API resources programmatically after `tower_cli` has been imported.","wrong":"from tower_cli.cli import get_resource","symbol":"tower_cli.get_resource","correct":"import tower_cli\nresource = tower_cli.get_resource('job_templates')"}],"quickstart":{"code":"import os\nimport tower_cli\n\n# Configure tower_cli using environment variables\n# Recommended: set TOWER_HOST and TOWER_TOKEN for secure authentication.\n# Example: export TOWER_HOST='https://your-awx-instance.com'\n#          export TOWER_TOKEN='your_api_token'\n#          export TOWER_VERIFY_SSL='False' # if using self-signed certs\n\nhost = os.environ.get('TOWER_HOST', 'https://localhost')\ntoken = os.environ.get('TOWER_TOKEN', '')\nverify_ssl_str = os.environ.get('TOWER_VERIFY_SSL', 'True').lower()\nverify_ssl = verify_ssl_str == 'true' or verify_ssl_str == '1'\n\nif not token:\n    print(\"WARNING: TOWER_TOKEN environment variable not set. This example will likely fail.\")\n    print(\"Please set TOWER_HOST and TOWER_TOKEN (and optionally TOWER_VERIFY_SSL) environment variables.\")\n\n# Programmatically set configuration, this will override environment variables if set\n# This also persists to a config file by default, which can be useful but might be unintended.\n# For a single script run, relying solely on env vars is often preferred.\n# If you need to set explicitly in code:\n# tower_cli.get_resource('settings').modify(\n#     TOWER_HOST=host,\n#     TOWER_TOKEN=token,\n#     TOWER_VERIFY_SSL=verify_ssl\n# )\n\nprint(f\"Attempting to connect to Tower/AWX at: {host}\")\nprint(\"Listing the first 5 job templates...\")\n\ntry:\n    # Using tower_cli.get_resource() to interact with the API\n    # Configuration will be picked up from environment variables.\n    job_templates_resource = tower_cli.get_resource('job_templates')\n    job_templates = job_templates_resource.list(page_size=5)\n\n    if job_templates:\n        print(\"Successfully retrieved job templates:\")\n        for jt in job_templates:\n            print(f\"- ID: {jt['id']}, Name: {jt['name']}\")\n    else:\n        print(\"No job templates found or access denied. Check your permissions and connection.\")\n\nexcept tower_cli.exceptions.TowerCLIError as e:\n    print(f\"An error occurred while interacting with Tower/AWX: {e}\")\n    print(\"Please ensure your TOWER_HOST, TOWER_TOKEN, and TOWER_VERIFY_SSL environment variables are correctly set and accessible.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to use `ansible-tower-cli` programmatically within a Python script. It relies on environment variables (`TOWER_HOST`, `TOWER_TOKEN`, `TOWER_VERIFY_SSL`) for configuration, which is the recommended approach for secure and flexible scripting. It then fetches and prints the first five job templates from the configured Tower/AWX instance. Ensure you have your instance details and API token set as environment variables before running."},"warnings":[{"fix":"Explicitly set `TOWER_VERIFY_SSL=False` in your environment variables, or use `--insecure` flag on the CLI, or ensure your Python environment trusts the SSL certificate of your Tower/AWX instance.","message":"The default behavior for `verify_ssl` changed from `False` to `True` in `v3.3.2`. If you were relying on SSL verification being off without explicitly setting it, your commands will now fail with SSL certificate errors.","severity":"breaking","affected_versions":">=3.3.2"},{"fix":"Use `tower-cli login` to obtain an API token and then set the `TOWER_TOKEN` environment variable for your CLI or programmatic interactions. Avoid embedding `--username` and `--password` directly in scripts or command lines.","message":"As of `v3.3.0`, `tower-cli login` introduced token-based authentication as the recommended method. While username/password can still be used directly in some commands, using API tokens is more secure and generally preferred, especially for programmatic access.","severity":"gotcha","affected_versions":">=3.3.0"},{"fix":"For transient or script-specific configurations, rely primarily on environment variables (`TOWER_HOST`, `TOWER_TOKEN`, etc.) which are picked up automatically by `tower_cli`. If you must modify settings in code, consider explicitly resetting or managing the config file location if persistence is not desired.","message":"When using `tower-cli` programmatically, configurations set via `tower_cli.get_resource('settings').modify()` persist to a local configuration file by default. This can lead to unexpected behavior if multiple scripts or users share the same configuration or if you intend for settings to be transient.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `ansible-tower-cli` is installed via `pip install ansible-tower-cli` within your active Python environment. If using a virtual environment, activate it. If installed, verify your PATH includes the directory where pip installs executables (e.g., `~/.local/bin` or `/usr/local/bin`).","cause":"The `tower-cli` executable is not in your system's PATH, or the package was not installed correctly.","error":"tower-cli: command not found"},{"fix":"If safe to do so (e.g., in a trusted internal network with self-signed certs), set the environment variable `TOWER_VERIFY_SSL=False` or use the `--insecure` flag with CLI commands. Otherwise, ensure your system's certificate store trusts the certificate of your Tower/AWX instance.","cause":"SSL certificate verification failed. This can happen if your Tower/AWX instance uses a self-signed certificate, or the certificate is not trusted by your system's certificate store, especially after the `verify_ssl` default changed in v3.3.2.","error":"requests.exceptions.SSLError: HTTPSConnectionPool(...) Max retries exceeded with url: ... Caused by SSLError(CertificateError(\"hostname '...' doesn't match '...'\",)"},{"fix":"Ensure `TOWER_TOKEN` environment variable is set with a valid, active API token. Alternatively, if using username/password, verify `TOWER_USERNAME` and `TOWER_PASSWORD` are correct and the user has permissions. Use `tower-cli login` to generate a new token.","cause":"Your API request to Tower/AWX was rejected due to missing or invalid authentication credentials (e.g., incorrect token, username, or password).","error":"Authentication required"},{"fix":"Double-check the resource ID or name for typos. Verify that the authenticated user has appropriate read permissions on the resource you are trying to access in Ansible Tower/AWX. Use `tower-cli <resource_type> list` to confirm available resources and their IDs.","cause":"You attempted to access a resource (e.g., job template, inventory) by an ID or name that does not exist or is inaccessible to your authenticated user.","error":"The requested object could not be found."}]}