ansible-help

A lightweight CLI for discovering the playbooks and roles in an Ansible repo and showing the most likely inputs they accept.

This tool is intended to inspect an Ansible repository when you point it at one. It looks for local and collection-scoped content, follows simple import_playbook wrappers, and prints a readable summary that makes it easier to understand what a playbook or role is for and which variables are likely relevant.

This repository itself is not an Ansible repo, so there are no collection directories to discover here by default. Collection lookup only matters when the CLI is run against a real Ansible project that defines ansible.cfg and/or a configured collections_path.

---

How it works

The CLI performs three core tasks:

Mode	Trigger	What it does
list	No arguments	Lists available playbooks and roles in the current repo.
show	One playbook or role name	Prints the playbook/role description and the inferred input list.
help	-h or --help	Prints the usage text for the tool.

The implementation is repo-aware and looks for content in the repo's configured collection roots, plus the standard Ansible default fallback. The exact search locations are driven by ansible.cfg via collections_path when present, and when that value is not set Ansible falls back to ~/.ansible/collections.

Local repo content is still searched in:

• playbooks/*.yml
• roles/*

Collection content is searched under each configured collection root, e.g.:

• ./collections/ansible_collections/*/*/playbooks/*.yml
• ~/.ansible/collections/ansible_collections/*/*/playbooks/*.yml
• any additional path configured in collections_path

It also tries to recover metadata from a few common Ansible conventions:

• top-of-file YAML docblocks starting with #
• meta/argument_specs.yml for role options
• meta/main.yml galaxy_info.description
• import_playbook wrapper playbooks
• simple heuristic detection of variable names from set_fact and include-role patterns

That means it is most useful as a human-facing discovery tool, not as a replacement for Ansible execution or full variable validation.

---

Getting started

Install the package and run it from the repo root:

python -m pip install -e .
ansible-help

When run against an Ansible repo, the CLI expects to find an ansible.cfg and then resolves collection locations according to collections_path in that config. If collections_path is unset, Ansible falls back to ~/.ansible/collections. If this repository is being used as the working directory, there is no Ansible project metadata to scan, so no collection directories are expected.

Installation

This project is configured as a Python package with a console script entry point. The pyproject.toml exposes:

[project.scripts]
ansible-help = "ansible_help.cli:main"

In practice, the installed command name is ansible-help and the underlying module path is src/ansible-help/cli.py.

---

Repo assumptions

This tool is designed to scan an Ansible repo that has an ansible.cfg file. The collections_path setting in that file controls where collection code is looked up, so the collection directories may live under a custom path rather than a fixed ./collections folder.

This project itself is not that kind of repo, so no collection directories are expected in this workspace unless you explicitly point the tool at an external Ansible checkout.

A typical setup looks like this:

[defaults]
collections_path = ./collections

which resolves to a structure like:

repo-root/
├── ansible.cfg
├── collections/
│   └── ansible_collections/
│       └── my_namespace/
│           └── my_collection/
│               ├── playbooks/
│               └── roles/
├── playbooks/
├── roles/
└── ...

If collections_path is not set, Ansible falls back to ~/.ansible/collections by default, and the CLI follows that same default behavior.

If you are not in the repo root, or if the target repository does not have an ansible.cfg, the CLI will not locate the repo and will stop immediately.

---

Modes

List mode

Running with no arguments enumerates everything the tool can find.

ansible-help

Example output is a two-column listing of playbooks and roles:

For more information on a specific playbook or role, type ansible-help <name>

Playbooks:
---------------
playbooks.deploy_app        Deploy an application stack.
my_namespace.my_collection.foo  Run the foo collection playbook.

Roles
---------------
roles.my_role               Role for setting up a service.
my_namespace.my_collection.my_role  Collection role for deployment tasks.

The list is sorted alphabetically and intentionally hides low-signal wrapper playbooks when they are only forwarding to another playbook without adding useful metadata.

Show mode

Pass a playbook name or role name to print a more detailed help view.

actions="ansible-help <name>"

Examples:

ansible-help playbooks.deploy_app
ansible-help my_namespace.my_collection.foo
ansible-help roles.my_role
ansible-help my_namespace.my_collection.my_role
ansible-help ./playbooks/deploy_app.yml

For a playbook, the output may include:

• the playbook description
• a summary paragraph from the docblock
• a generated ansible-playbook ... [-e "..."] invocation
• a table of inputs with their status and detail
• examples copied from the docblock

For a role, the output may include:

• a role description from galaxy_info or docblock metadata
• an ansible.builtin.include_role name=... vars: [...] summary
• inferred input names and details
• example usage

Help mode

ansible-help -h
ansible-help --help

This prints:

A utility to parse available ansible operations

ansible-help [-h] [playbook] [role]

   -h         Show Command Line options for ansible-help
   playbook   Show Help menu for a given playbook
   role       Show Help menu for a given role

---

What the tool can infer

The CLI is intentionally heuristic and best-effort. It tries to infer from real Ansible conventions rather than requiring a strict schema.

Playbook inputs

When a playbook has a docblock with sections such as:

• Inputs:
• Required inputs:
• Command Line Arguments:
• Parameters:

those are parsed and rendered as argument metadata.

If those sections are absent, the tool falls back to heuristics such as:

• set_fact tasks with _input variable resolution
• include-role mapping patterns
• meta/argument_specs.yml for associated roles
• wrapper playbook resolution through import_playbook

Role inputs

For roles, the tool prefers:

1. meta/argument_specs.yml
2. role docblock sections
3. best-effort heuristics when metadata is sparse

This is useful for roles that are passed in via ansible.builtin.include_role and where the actual CLI-facing variables are not always obvious from the task body alone.

---

Example usage

# Discover everything in the repo
ansible-help

# Inspect a local playbook
ansible-help playbooks.deploy_app

# Inspect a collection playbook by FQCN
ansible-help my_namespace.my_collection.foo

# Inspect a local role
ansible-help roles.my_role

# Inspect a collection role by FQCN
ansible-help my_namespace.my_collection.my_role

You can also pass a direct file path when the playbook is not referenced by a repo name:

ansible-help ./playbooks/deploy_app.yml

---

Limitations

This is a documentation and discovery helper, not a fully featured Ansible execution engine. It is intentionally conservative about what it claims to know.

The most important limitations are:

• it reads static YAML and docblocks, not live runtime state
• it cannot know every dynamic variable created at execution time
• it is heuristic about inferred input names and defaults
• it only resolves a single import_playbook wrapper hop before falling back to the current playbook

For anything beyond discovery, the canonical sources remain the Ansible playbooks, roles, and their argument specs themselves.

---

Authoring playbook docblocks for ansible-help

Collection developers can make the tool much more useful by adding a short YAML docblock at the top of each playbook. ansible-help scans the first comment block it sees and uses it to populate the playbook name, summary, examples, and input list.

A well-structured docblock looks like this:

---
# Deploy a service into a target environment.
#
# Inputs:
#   environment (required, defaults to prod) - Target environment to deploy into.
#   service_name (required) - Name of the service to provision.
#   region (optional, defaults to us-east-1) - Deployment region.
#   overwrite (optional) - Replace any existing deployment if true.
#
# Examples:
#   ansible-playbook playbooks/deploy_service.yml -e "environment=prod service_name=api region=us-east-1"
#   ansible-playbook playbooks/deploy_service.yml -e "environment=dev service_name=api overwrite=true"

- name: Deploy service
  hosts: localhost
  gather_facts: false
  vars:
    environment: "{{ environment | default('prod') }}"
    service_name: "{{ service_name }}"
    region: "{{ region | default('us-east-1') }}"

How ansible-help uses this information

The tool looks for a top-of-file comment block similar to the one above and uses it in a few specific ways:

• it reads the first descriptive sentence as the playbook summary
• it parses the Inputs: section into a table of names, required/optional status, and detail text
• it keeps example commands from the Examples: section and prints them under the playbook help output
• it avoids guessing when the metadata is clear and explicit

This means the most valuable thing a collection author can do is add a brief description and a compact list of the actual inputs the playbook accepts.

Recommended conventions

Keep the docblock at the top of the file, before the first play or task. A simple pattern is:

---
# Short summary sentence.
#
# Inputs:
#   input_name (required|optional, defaults to ...) - What it is used for.
#
# Examples:
#   ansible-playbook ...

For collection playbooks, this is especially helpful because the tool can then present a cleaner experience for users who are browsing a collection from a shared repo, or for developers who do not want to read the entire playbook to understand its runtime contract.

Why this matters

The CLI is a best-effort helper. It can infer some things from task logic, argument specs, and role metadata, but it is much more reliable when the playbook itself documents its expected inputs and sample usage plainly. Good metadata reduces ambiguity and makes help output much easier to trust.

In short: if you want ansible-help to be accurate and user-friendly for your collection, document the playbook at the top of the YAML file and keep the input names and examples aligned with the actual task variables.

---

Notes

The CLI is intentionally simple to use:

• no configuration flags
• no repo-specific setup beyond being in the right directory
• no remote API dependencies
• no generated release machinery or changelog workflow

The goal is straightforward: help a developer quickly answer, “What playbooks are available in this repo, and what inputs do they likely expect?”