Apps

ansible-core ships ten end-user CLIs. Nine live in lib/ansible/cli/ and share a base class; the tenth, ansible-test, lives in test/lib/ansible_test/ and is packaged separately.

graph LR
    subgraph "Workload CLIs"
        AD[ansible<br/>ad-hoc]
        PB[ansible-playbook]
        PULL[ansible-pull]
        CON[ansible-console]
    end
    subgraph "Inspection CLIs"
        DOC[ansible-doc]
        INV[ansible-inventory]
        CFG[ansible-config]
    end
    subgraph "Content CLIs"
        GAL[ansible-galaxy]
        VLT[ansible-vault]
    end
    subgraph "Test CLI"
        TST[ansible-test]
    end
    AD & PB & PULL & CON & DOC & INV & CFG & GAL & VLT --> CLIBASE[CLI base class<br/>lib/ansible/cli/__init__.py]
    TST --> ATBASE[ansible_test._internal<br/>test/lib/ansible_test/]

The shared CLI base class

Every workload/inspection/content CLI subclasses CLI from lib/ansible/cli/__init__.py. The base class:

• Enforces _PY_MIN = (3, 12) at import time.
• Initializes locale (UTF-8 required) and verifies stdin/stdout/stderr are blocking.
• Builds an argparse parser via init_parser() and the option groups in lib/ansible/cli/arguments/option_helpers.py.
• Loads vault secrets (PromptVaultSecret, get_file_vault_secret).
• Constructs the shared object graph: DataLoader → InventoryManager → VariableManager.
• Bootstraps the plugin loader (init_plugin_loader()).
• Runs the subclass's run().

The CLI subclass overrides init_parser() to add command-specific options and run() to implement the actual workflow.

Per-CLI summaries

CLI	File	What it does
ansible	lib/ansible/cli/adhoc.py	Ad-hoc execution: run a single module against a host pattern, no playbook required
ansible-playbook	lib/ansible/cli/playbook.py	The headline CLI: run YAML playbooks against an inventory
ansible-pull	lib/ansible/cli/pull.py	Inverted pull-mode: clone a repo on the target and run a playbook locally
ansible-console	lib/ansible/cli/console.py	REPL-style interactive shell using cmd
ansible-doc	lib/ansible/cli/doc.py	Render plugin/module documentation
ansible-inventory	lib/ansible/cli/inventory.py	Inspect inventory: graph, list, host-detail
ansible-config	lib/ansible/cli/config.py	Inspect/list/validate config options
ansible-galaxy	lib/ansible/cli/galaxy.py	Install/build/publish collections and roles
ansible-vault	lib/ansible/cli/vault.py	Encrypt/decrypt files and inline strings
ansible-test	test/lib/ansible_test/_util/target/cli/ansible_test_cli_stub.py	Sanity, unit, and integration tests

The full per-CLI breakdown is below.

ansible (ad-hoc) — lib/ansible/cli/adhoc.py

Defines AdHocCLI. Builds a one-task playbook on the fly from -m <module> -a <args> against a host pattern, hands it to TaskQueueManager, and exits. Used for quick ansible all -m ping style sanity checks. The unique flags are -m (module name, default command) and -a (module arguments).

It also has an unusual side path: when invoked as part of OpenSSH's SSH_ASKPASS flow (single argv element + the _ANSIBLE_SSH_ASKPASS_SHM env var), lib/ansible/cli/__init__.py short-circuits to lib/ansible/cli/_ssh_askpass.py and exits before any of the adhoc machinery runs. This lets ssh prompt for passwords through the controller.

ansible-playbook — lib/ansible/cli/playbook.py

Defines PlaybookCLI. The path is straightforward:

1. Parse args. Add inventory, runtask, vault, fork, and check-mode options via option_helpers.
2. Load each playbook via Playbook.load() from lib/ansible/playbook/__init__.py.
3. Construct a PlaybookExecutor (lib/ansible/executor/playbook_executor.py) and call .run().

Special modes that bypass execution: --syntax-check (parse but don't run), --list-tasks, --list-tags, --list-hosts. --start-at-task and --step modify the iteration; the latter prompts before each task.

ansible-pull — lib/ansible/cli/pull.py

PullCLI. The inverted-pull pattern: instead of pushing from a controller to many hosts, every node periodically pulls. The CLI clones (or updates) a Git/Mercurial/SVN/Bazaar repo, then invokes ansible-playbook locally with -i 'localhost,' -c local. Used in immutable-infrastructure flows where you want hosts to converge themselves on a schedule.

The Bryan-Bonarrigo-era pattern of "every host runs a cron that pulls the playbook" is encoded directly in this CLI. It hands off to ansible-playbook rather than reimplementing the executor.

ansible-console — lib/ansible/cli/console.py

ConsoleCLI. A REPL built on Python's stdlib cmd module. Each line typed becomes a single ad-hoc task against the current host pattern. State (cwd, current group, become settings) persists across commands. Useful for exploration and quick iteration; the implementation is small (~600 lines).

ansible-doc — lib/ansible/cli/doc.py

DocCLI. The largest non-galaxy CLI at 1,676 lines. Reads the DOCUMENTATION, EXAMPLES, and RETURN blocks out of plugin and module source files (or sidecar YAML), and renders them as plaintext, JSON, or by-keyword search.

Modes:

• ansible-doc <module> — pretty-print one plugin's doc.
• ansible-doc -t <plugin_type> <name> — pick the plugin type explicitly.
• ansible-doc -l — list every plugin of a type.
• ansible-doc --metadata-dump — JSON dump of all docs (used by docs.ansible.com builders).
• ansible-doc -j <plugin> — JSON output for a single plugin.
• ansible-doc --keyword — list playbook keywords (from lib/ansible/keyword_desc.yml).

Big because it has to handle a lot of plugin types and edge cases (deprecated plugins, redirects, sidecar docs, role argument specs).

ansible-inventory — lib/ansible/cli/inventory.py

InventoryCLI. Reports on what the inventory plugins resolve to.

• --list — JSON dump of every host's variables (used by other tools as a stable inventory format).
• --graph — pretty tree of groups/hosts.
• --host <name> — variable view for one host.
• --toml / --yaml — alternate output formats.

Implemented as a thin wrapper around InventoryManager and VariableManager.

ansible-config — lib/ansible/cli/config.py

ConfigCLI. Inspect Ansible configuration:

• list — every config option, with descriptions and current effective values, derived from lib/ansible/config/base.yml.
• dump — same but only options whose value differs from the default.
• view — render a config file (with vault-decryption).
• init — emit a starter ansible.cfg.
• validate — check a config file for typos and unknown keys.

The 28k-line lib/ansible/cli/config.py file (vs. the 7.8k-line base.yml) is mostly the formatting and per-source dispatch logic.

ansible-galaxy — lib/ansible/cli/galaxy.py

GalaxyCLI. The largest CLI in the tree at 1,889 lines. Two main domains:

• Roles — install, list, search, init, build, info, publish (legacy Galaxy v1 API).
• Collections — install, list, build, init, info, verify, download, publish (Galaxy v3 API).

Subcommands are nested two levels deep: ansible-galaxy collection install, ansible-galaxy role install, etc. The collection install path dependency-resolves via resolvelib and pulls from lib/ansible/galaxy/collection/__init__.py. See Features → Collections for the deeper view.

ansible-vault — lib/ansible/cli/vault.py

VaultCLI. Drives lib/ansible/parsing/vault/__init__.py for encrypt/decrypt operations:

• create / edit — encrypt or open an existing encrypted file in $EDITOR.
• view — decrypt to stdout.
• encrypt / decrypt — file-level operations.
• encrypt_string — produce an inline !vault YAML scalar for embedding in playbooks.
• rekey — change the vault password.

Vault id support (--vault-id label@source) lets one playbook draw on multiple vault secrets simultaneously. See Systems → Vault encryption.

ansible-test — test/lib/ansible_test/

The odd one out. Doesn't share CLI because it never operates on a host pattern; it's a build/test driver. Three primary commands — sanity, units, integration — plus utilities (coverage, env, windows-integration, network-integration).

The bin entrypoint is the symlink bin/ansible-test → test/lib/ansible_test/_util/target/cli/ansible_test_cli_stub.py. The stub initializes the package and dispatches to the real command. See How to contribute → Testing for the full picture, and How to contribute → Tooling for the CI integration.

Cross-links

• Systems → Executor — what the workload CLIs hand off to.
• Systems → Plugin loader — what every CLI initializes early.
• Features → Collections — what ansible-galaxy and the runtime resolver work on.
• Reference → Configuration — what ansible-config reads.