Command-Line Tools

Relevant source files

The following files were used as context for generating this wiki page:

• lib/ansible/cli/adhoc.py
• lib/ansible/cli/playbook.py
• lib/ansible/cli/vault.py
• lib/ansible/cli/galaxy.py
• lib/ansible/cli/doc.py
• lib/ansible/modules/uri.py
• lib/ansible/modules/command.py

The Ansible command-line tools are the primary user interface for interacting with the Ansible automation engine. They provide functionalities ranging from running ad-hoc commands and executing entire playbooks to managing encrypted secrets and community-contributed content. These tools are implemented as Python classes located in the lib/ansible/cli/ directory.

Each command-line tool inherits from a common CLI base class, which provides a standardized structure for argument parsing, configuration, and execution. This modular design allows for consistent behavior across the toolset while accommodating the specific needs of each command.

Core Architecture

All command-line tools in Ansible are built upon a shared base class, ansible.cli.CLI. This class establishes a common execution pattern and structure for argument parsing.

The following diagram illustrates the inheritance hierarchy of the main CLI tools.

Sources: lib/ansible/cli/doc.py, lib/ansible/cli/adhoc.py, lib/ansible/cli/playbook.py, lib/ansible/cli/vault.py, lib/ansible/cli/galaxy.py

The base CLI class defines a simple lifecycle for each tool:

1. init_parser(): Each subclass implements this method to define its specific command-line arguments and options using Python's argparse.
2. post_process_args(): This method is called after initial argument parsing to perform any necessary modifications or validation of the provided options.
3. run(): This is the main execution method where the core logic of the tool is implemented.

Sources: lib/ansible/cli/doc.py:100-119, lib/ansible/cli/galaxy.py:53-56, lib/ansible/cli/vault.py:57-61

Key CLI Tools

Tool	Class	Purpose	Source File
ansible	AdHocCLI	Executes single, ad-hoc commands on remote hosts.	lib/ansible/cli/adhoc.py
ansible-playbook	PlaybookCLI	Executes Ansible playbooks.	lib/ansible/cli/playbook.py
ansible-doc	DocCLI	Displays documentation for Ansible plugins.	lib/ansible/cli/doc.py
ansible-galaxy	GalaxyCLI	Manages roles and collections from Ansible Galaxy.	lib/ansible/cli/galaxy.py
ansible-vault	VaultCLI	Manages encrypted files.	lib/ansible/cli/vault.py

ansible-playbook

The ansible-playbook command is the primary tool for executing Ansible playbooks. It is implemented in the PlaybookCLI class.

Execution Flow

The run() method orchestrates the execution. It creates a PlaybookExecutor instance, which is responsible for loading, parsing, and running the playbook tasks against the specified inventory.

The following sequence diagram shows the high-level interaction of components during a playbook run.

Sources: lib/ansible/cli/playbook.py:70-101

Key Options

The init_parser method defines several important options for controlling playbook execution:

• --list-tasks: Lists all the tasks that would be executed.
• --start-at-task: Starts execution at a specific task.
• --step: Runs in interactive mode, confirming each task before execution.
• --syntax-check: Performs a syntax check on the playbook without executing it.

Sources: lib/ansible/cli/playbook.py:53-68

ansible (Ad-Hoc)

The ansible command is used for running simple, one-off commands on a set of hosts. It is implemented in the AdHocCLI class. Unlike ansible-playbook, it does not use a playbook file. Instead, it constructs a temporary play in memory to execute a single task.

Execution Flow

The run() method in AdHocCLI is responsible for:

1. Programmatically creating a Play object.
2. Adding a single task to the play based on the module (-m) and arguments (-a) provided on the command line.
3. Instantiating a TaskQueueManager to manage the execution of this single task across the inventory.
4. Processing and displaying the results.

Sources: lib/ansible/cli/adhoc.py:126-174

Key Options

• -m, --module-name: The name of the module to execute (e.g., ping, command).
• -a, --args: A string of arguments to pass to the module.
• -B, --background: Run the command asynchronously in the background.
• -P, --poll: Poll interval for asynchronous jobs (used with -B).

Sources: lib/ansible/cli/adhoc.py:69-80

ansible-doc

The ansible-doc tool is used to display documentation for Ansible plugins like modules, lookups, and filters. It is implemented in the DocCLI class.

Execution Flow

The run() method in DocCLI contains the primary logic, which varies based on the provided command-line flags.

Sources: lib/ansible/cli/doc.py:535-598

Key Features

Feature	Option	Description
Plugin Type	-t, --type	Specifies the type of plugin to document (e.g., module, lookup, filter). Defaults to module.
List Plugins	-l, --list	Lists all available plugins of a given type with their short descriptions.
List Files	-F, --list_files	Lists all available plugins and their source file paths.
Show Snippet	-s, --snippet	Displays a playbook snippet for using the plugin.
JSON Output	-j, --json	Formats the output as JSON instead of plain text.

Sources: lib/ansible/cli/doc.py:441-464

The DocCLI also includes a RoleMixin to handle documentation for roles, allowing it to find and parse argument_specs.yml or meta/main.yml files.

Sources: lib/ansible/cli/doc.py:122, lib/ansible/cli/doc.py:125-274

ansible-galaxy

The ansible-galaxy command is the tool for managing Ansible content, primarily roles and collections, from Ansible Galaxy and other sources. It is implemented in the GalaxyCLI class.

Subcommands

GalaxyCLI uses argparse subparsers to implement a variety of subcommands. The run() method instantiates a Galaxy object and calls the method corresponding to the chosen subcommand.

Sources: lib/ansible/cli/galaxy.py:58-132, lib/ansible/cli/galaxy.py:141-144

A summary of primary subcommands:

Subcommand	Description
init	Creates a skeleton structure for a new role or collection.
install	Installs roles or collections.
list	Lists installed roles or collections.
remove	Removes an installed role or collection.
collection	A sub-command with its own set of actions for managing collections (e.g., build, publish).

Sources: lib/ansible/cli/galaxy.py:60-132

ansible-vault

The ansible-vault command provides a way to manage encrypted files and variables within an Ansible project. It is implemented in the VaultCLI class.

Vault Actions

Similar to ansible-galaxy, VaultCLI uses subparsers to define its primary actions. The run() method dispatches to a corresponding execute_<action> method.

Action	execute_* Method	Description
create	execute_create	Creates a new encrypted file.
decrypt	execute_decrypt	Decrypts an existing vaulted file.
edit	execute_edit	Edits an existing vaulted file, decrypting for edit and re-encrypting on save.
encrypt	execute_encrypt	Encrypts an existing plaintext file.
encrypt_string	execute_encrypt_string	Encrypts a string provided on the command line.
rekey	execute_rekey	Changes the password for a vaulted file.
view	execute_view	Displays the decrypted content of a vaulted file to standard output.

Sources: lib/ansible/cli/vault.py:63-100, lib/ansible/cli/vault.py:107-113

The core logic for encryption and decryption is handled by the VaultLib class, which is instantiated within the VaultCLI methods.

Sources: lib/ansible/cli/vault.py:116