Metadata-Version: 2.4
Name: ansible-help
Version: 1.0.5
Summary: CLI helpers for discovering Ansible playbooks, roles, and command-line options.
Author: Daniel Davis
Maintainer: Daniel Davis
License: MIT
Project-URL: Homepage, https://github.com/fullsteam-corp-shared/pypi-ansible-help
Project-URL: Documentation, https://github.com/fullsteam-corp-shared/pypi-ansible-help#readme
Project-URL: Repository, https://github.com/fullsteam-corp-shared/pypi-ansible-help.git
Project-URL: Issues, https://github.com/fullsteam-corp-shared/pypi-ansible-help/issues
Keywords: ansible,cli,playbooks
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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:

```bash
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:

```toml
[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:

```ini
[defaults]
collections_path = ./collections
```

which resolves to a structure like:

```text
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.

```bash
ansible-help
```

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

```text
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.

```bash
actions="ansible-help <name>"
```

Examples:

```bash
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

```bash
ansible-help -h
ansible-help --help
```

This prints:

```text
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

```bash
# 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:

```bash
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:

```yaml
---
# 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:

```yaml
---
# 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?”
