ansible-inventory

Display the default inventory

$ ansible-inventory --list

$ ansible-inventory --list [[-i|--inventory-file]] [path/to/file_or_script_or_directory]

$ ansible-inventory --list [[-y|--yaml]]

$ ansible-inventory --list --output [path/to/file]

ansible-inventory [-i INVENTORY] [--list | --graph | --host HOSTNAME | --export] [options]

Examples:
ansible-inventory -i /etc/ansible/hosts --list
ansible-inventory -i /path/to/inventory.yaml --graph
ansible-inventory -i my_dynamic_inventory_script.py --host webserver1 -v

-i INVENTORY, --inventory=INVENTORY
    Specifies the inventory file, directory, or dynamic inventory script to use. This option is often required for most commands.

--list
    Lists all hosts and groups from the inventory in JSON format. This is the default action if no other action option (like --graph or --host) is specified.

--graph
    Generates a graphical representation (ASCII art) of the inventory groups and hosts, showing their hierarchical relationships.

--host=HOSTNAME
    Displays detailed information and all resolved variables for a specific host within the inventory. Essential for debugging variable precedence.

--export
    Exports the inventory in a format suitable for use with -i, typically JSON, enabling inventory transformation or further processing.

-v, --verbose
    Enables verbose output. Can be specified multiple times (e.g., -vvv) for increasing levels of detail, which is particularly useful for debugging.

--yaml
    Outputs --list or --host information in YAML format instead of the default JSON, often preferred for readability.

--json
    Outputs --list or --host information in JSON format (this is the default behavior).

--toml
    Outputs --list or --host information in TOML format (requires the toml Python package to be installed).

--show-enabled-plugins
    Lists all currently enabled inventory plugins that Ansible is configured to use, which can help diagnose inventory loading issues.

--help
    Displays a help message for the command and exits.

ansible-inventory
is a powerful command-line utility provided by Ansible, designed to help users view, manage, and debug their Ansible inventories. It offers a structured and comprehensive way to inspect the hosts, groups, variables, and host/group relationships defined within any inventory source, whether it's a static file (INI, YAML) or a dynamic inventory script. Its primary applications include verifying the correctness and structure of the inventory, listing all available hosts and their associations, showing detailed information and resolved variables for specific hosts, and understanding the complex variable precedence rules. This tool is indispensable for any Ansible user, as it provides critical insights into how Ansible perceives the environment before executing playbooks, thereby significantly aiding in troubleshooting, ensuring proper targeting of systems, and confirming that playbooks receive the expected variable values. It serves as a diagnostic window into your Ansible-managed infrastructure.

Using ansible-inventory requires an existing Ansible installation on the system.
Dynamic inventory scripts must be executable and strictly adhere to Ansible's dynamic inventory protocol to provide valid JSON output.
Understanding variable precedence can be complex; ansible-inventory --host is an invaluable tool for debugging how Ansible resolves variables for a specific host, as it shows the final, merged variable values.
For very large or highly complex dynamic inventories, performance might be a consideration, as the inventory script must be executed to gather all data, potentially leading to longer execution times.

Debugging Inventory: Quickly check if hosts, groups, and their relationships are correctly defined and recognized by Ansible.
Variable Inspection: Determine the final, merged value of a variable for a specific host, considering all sources (inventory files, group_vars, host_vars, roles, etc.). This is critical for troubleshooting playbook behavior.
Listing Hosts: Obtain a machine-readable list of all hosts and their associated groups, useful for scripting or integration with other automation tools.
Graph Visualization: Understand the hierarchical relationships between groups and hosts using the --graph option, which provides an ASCII art representation of the inventory structure.

By default, ansible-inventory --list and ansible-inventory --host output information in JSON format.
The --yaml and --toml options allow switching the output format, which can be useful for enhanced readability or for integration with tools that prefer those formats.
The --graph output is always text-based, providing an ASCII art representation of the inventory structure, illustrating group nesting and host membership.

ansible-inventory was introduced into the Ansible ecosystem to provide a dedicated and robust tool for inspecting and debugging Ansible inventories. Prior to its existence, inventory introspection was less comprehensive, often relying on simpler methods like ansible --list-hosts or custom scripting, which lacked the detailed variable resolution capabilities. Its development significantly streamlined inventory management and debugging workflows, making it an indispensable utility for Ansible users, especially when dealing with complex or dynamic inventory sources.

ansible(1), ansible-playbook(1), ansible-doc(1), ansible-galaxy(1), ansible-vault(1)